Skip to main content

Handle scope updates in organization tokens

With the above setup, you can send invitations via email, and invitees can join the organization with the assigned role.

Users with different organization roles will have different scopes (permissions) in their organization tokens. Both your client app and backend services should check these scopes to determine visible features and permitted actions.

As mentioned earlier, the organization template serves as a key access control layer to protect organization permissions or organization-level APIs. Be sure to review the authorization sections and choose the authorization model that best fits your product.

note:Protect organization (non-API) permissions

Protect organization-level API resources

This chapter focuses on permission management and best practices for handling scope changes and permissions in Logto organization tokens.

Handle scope updates in organization tokens​

Managing scope updates in organization tokens involves:

Revoke existing scopes​

For instance, demoting an admin to a non‑admin member should remove scopes from the user. In such cases, clear the cached organization token and fetch a new one with a refresh token. The reduced scopes will be reflected immediately in the newly issued organization token.

Grant new scopes​

This can be divided into two scenarios:

Grant new scopes that are already defined in your auth system​

Similar to revoking scopes, if the newly granted scope is already registered with the auth server, issue a new organization token and the new scopes will be reflected immediately.

Grant new scopes that are newly introduced into your auth system​

In this case, trigger a re‑login or re‑consent process to update the user’s organization token. For example, call the signIn method in the Logto SDK.

Check permissions in real time and update the organization token​

Logto provides a Management API to fetch real‑time user permissions in the organization.

Compare the scopes in the user’s organization token with the real‑time permissions to determine if the user has been promoted or demoted.

  • If demoted, clear the cached organization token and the SDK will automatically issue a new one with the updated scopes.

    const { clearAccessToken } = useLogto();

    ...
    // If fetched real-time scopes have fewer scopes than the organization token scopes
    await clearAccessToken();

    This does not require a re‑login or re‑consent process. New organization tokens will be issued automatically by the Logto SDK.

  • If a new scope is introduced into your auth system, trigger a re‑login or re‑consent process to update the user’s organization token. For example, with the React SDK:

    const { clearAllTokens, signIn } = useLogto();

    ...
    // If fetched real-time scopes have newly assigned scopes than the organization token scopes
    await clearAllTokens();
    signIn({
      redirectUri: '<your-sign-in-redirect-uri>',
      prompt: 'consent',
    });

    The above code triggers a navigation to the consent screen and auto‑redirects back to your app with updated scopes in the user’s organization token.