Resources and permissions

In Goiabada, you can define both resources and permissions. Each resource can have multiple permissions associated with it.

You can assign these permissions to users, groups, or clients as needed.

Scope format

When you pair a resource with a permission, it forms a scope, both in the authorization request and within the tokens.

Format: resource-identifier:permission-identifier

Example:

If you have:

• A resource with identifier: product-api
• A permission with identifier: delete-product

The resulting scope will be: product-api:delete-product

This scope can then be requested in authorization requests and will appear in access tokens, allowing fine-grained access control to your APIs and resources.

Permission identifiers are scoped to their resource

A permission identifier only has meaning within the resource it belongs to. Two resources can each define a permission called read, and those are two distinct permissions: granting one conveys nothing about the other.

So if you have product-api:read and reports-api:read, a client or user granted product-api:read cannot use reports-api:read. You must grant each one separately.

This is worth knowing because reusing short identifiers like read, write and delete across resources is normal and expected, and it is what makes the resource half of the scope load-bearing rather than decorative. It applies to the authserver resource too: a manage permission you create on your own resource is unrelated to the built-in authserver:manage.

System-level resource

The authserver resource is a system-level resource used internally by Goiabada. It has special protections:

• Its resource identifier cannot be changed (renaming is blocked)
• It cannot be deleted
• Its description can be modified
• New permissions can be added to it
• Its built-in permission identifiers cannot be renamed or deleted

The built-in permissions under the authserver resource are:

Permission identifier	Purpose
userinfo	Access to the /userinfo endpoint
manage-account	Self-service account management (Account API)
manage	Full admin access to all Admin API endpoints
admin-read	Read-only access to all Admin API endpoints
manage-users	Full access to user, group, and permission endpoints
manage-clients	Full access to client endpoints
manage-settings	Full access to settings and key endpoints

You can create additional custom permissions on the authserver resource if needed, but the built-in ones listed above are protected.

How to use scopes

1. Define resources - In the admin console, create resources that represent your APIs or protected areas (e.g., product-api, user-service)

2. Create permissions - For each resource, define the actions users or clients can perform (e.g., read, write, delete)

3. Assign permissions - Grant these permissions to:

   • Individual users
   • Groups (all members inherit the permissions)
   • Clients (for server-to-server access)

4. Request scopes - When initiating an authorization request, include the scopes your application needs:

   scope=openid product-api:read product-api:write

5. Validate access - In your API, check the access token for the required scopes before allowing access to resources