Skip to main content
Paid Feature

This is a paid feature.

You can click on the Enable Paid Features button on our dashboard, and follow the steps from there on. Once enabled, this feature is free on the provided development environment.

Working with Scopes

The allowed scopes are set during the creation process of an OAuth2 Client.

By default, our OAuth2 implementation adds the following built-in scopes:

  • email: adds the email, emails and email_verified claims into the ID Token and the User Info.
  • phoneNumber: adds the phoneNumber, phoneNumbers and phoneNumber_verified claims into the ID Token and the User Info
  • roles: adds the roles claim into the ID Token and Access Token.
    • This will contain the roles returned by getRolesForUser
    • This only works if the UserRoles recipe is initialized
  • permissions: adds the permissions claim into the ID Token and Access Token.
    • This will contain the list of permissions obtained by concatenating the result of getPermissionsForRole for all roles returned by getRolesForUser
    • This only works if the UserRoles recipe is initialized

Requesting Specific Scopes#

The client can request specific scopes by adding scope query param to the Authorization URL. The requested scopes have to be a subset of what is allowed for the client, otherwise the authentication request will fail. By default all scopes are granted to the client.

Overriding granted scopes#

If you want to manually modify the list of scopes that are granted to the client during the authentication flow you can do this by using overrides.


import OAuth2Provider from "supertokens-node/recipe/oauth2provider";

OAuth2Provider.init({
    override: {
        functions: (originalFunctions) => ({
            ...originalFunctions,
            getRequestedScopes: async (input) => {
                const originallyRequestedScopes = await originalFunctions.getRequestedScopes(input);
                const filteredScopes = originallyRequestedScopes.filter((scope) => scope !== "profile");
                return [...filteredScopes, "custom-scope"];
            },
        }),
    },
});
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI