Skip to main content

Work with scopes

Overview

The creation process of an OAuth2 Client determines the allowed scopes. By default, the OAuth2 implementation adds the following built-in scopes:

ScopeClaims AddedNotes
emailemail, emails, email_verifiedAdded to ID Token and User Info
phoneNumberphoneNumber, phoneNumbers, phoneNumber_verifiedAdded to ID Token and User Info
rolesThe roles return by getRolesForUserAdded to ID Token and Access Token
permissionsThe list of permissions obtained by concatenating the result of getPermissionsForRole for all roles returned by getRolesForUserAdded to ID Token and Access Token

Request specific scopes

The client can request specific scopes by adding scope query parameter to the Authorization URL. The requested scopes have to be a subset of what the client allows, otherwise the authentication request fails. By default, the client receives all scopes.

Override granted scopes

If you want to manually modify the list of scopes that the client receives 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"];
},
}),
},
});