Skip to main content

Configure organization template

We'll go through the process of configuring the organization template feature via Logto Console

First, navigate to Console > Organization template . You will see that the organization template includes two parts: Organization Roles and Organization Permissions. An organization template defines shared access control policies (permissions and roles) for multiple organizations.

Configure via Logto Console​

Create organization permission​

Organization permissions are a key part of organization template. These permissions are designed specifically for organizations within your product. Here's how to manage them:

  • Find the organization permissions tab: Go to the "Organization permissions" tab to see your existing permissions.
  • Add, delete, and edit: You can easily add new organization permissions, delete ones you don't need, and edit existing permissions as required.

Create organization role​

Logto supports two types of organization roles, this is the same as the user/system-level RBAC:

  • User: Roles that are assigned to users.
  • Machine-to-machine: Roles that are assigned to machine-to-machine applications.

Logto lets you define organization roles in a variety of ways to fit your system's structure:

Organization permissions only organization roles​

  • When to use: You have separate user/system endpoints and organization endpoints.
  • Explanation: This is the simplest approach if your product’s technical architecture and API design clearly separate user/system-level resources from organization resources. Your organization roles will only include the permissions you define for the organization.

API permissions only organization roles​

  • When to use: User/System-level and organization-level access control are handled by the same endpoints.
  • Explanation: Choose this if you want to manage all permissions through unified API resources.

Mixed API and organization permissions in organization roles​

  • When to use: You have separate endpoints defined for your product for user/system-level and organization level, but some user roles require a mix of both user-level and organization-level permissions.
  • Explanation: This offers the most flexibility, but can also be the most complex to manage.

Configure via Logto Management API​

Everything you can do in Console can also be done through Management API, including: Manage organization template to create, delete, or edit organization permissions and roles.

For a complete list of capabilities, please refer to our API reference

With the Logto Management API, you can create custom organization experiences, like allowing org admins to self-serve and create organizations. Check out this section to enable more organization-level features and management.

Handle member permission change​

Similar to API RBAC, member permissions may be altered during a session -- for instance, they may be assigned new roles or have existing role permissions modified.

What happens when a member permissions change? There are two cases.

No new permissions introduced into the system​

Current organization access tokens (a.k.a. organization token) will remain valid until they expire, even after a user’s organization permissions are changed. However, new permissions will be reflected in subsequent organization tokens, and any revoked permissions will be omitted.

note

Organization tokens have a fixed expiration time that can’t be changed, unlike generic access tokens.

Call Logto Management API endpoints periodically or establish a long-lived connection (e.g. using WebSocket) to dynamically fetch user’s organization permissions. Upon detecting changes, clear the existing organization token and newly issued tokens will automatically have organization permission scope changes reflected.

curl \
 -X GET https://[tenant_id].logto.app/api/organizations/{id}/users/{userId}/scopes \
 -H "Authorization: Bearer $ORGANIZATION_TOKEN"

When permission changes detected, clear the organization token from storage first, and then call the SDK method getOrganizationToken(organizationId) to acquire a new one. Newly issued organization token should have permission changes reflected.

New permission is introduced into the system and assigned to a member​

This happens when new permissions are introduced into your organization template. In this case, you’ll have to first include the newly introduced permission scopes when initializing Logto client. E.g.

new LogtoClient({
  appId: 'your-app-id',
  redirectUrl: 'your-redirect-url',
  scopes: [
    'urn:logto:scope:organizations',
    // ... your other existing organization permission scopes,
    'new-organization-permission-scope',
  ],
});

Secondly, each of your client application need to re-consent or re-login the users in order to receive the new permission change. Then the new permission scope will be reflected in new organization tokens.

Code example for re-consent:

signIn({ redirectUrl: 'your-redirect-url', prompt: 'consent' });