A scope is a named bundle of claims. A client that is allowed to request the scope can ask for it at login, and the claims the scope carries can then be released to that client. For the conceptual picture, see Entities.
Fields
| Field | What it is | Rules |
|---|---|---|
| Scope ID | The value the client sends in the scope parameter | Lowercase letters, digits and underscores, starting with a letter (^[a-z][a-z0-9_]*$). No colons, dots or hyphens. Unique within the tenant. Cannot be changed after creation |
| Description | A label for the scope, shown on the consent screen and in the console | Localised, one text per language. English is required. A language can be activated in Locales on System settings only when every text the server shows has a translation in it: scope and claim descriptions, client names, active form versions and the OTP and password templates (see Locales) |
| Claims | The user claims the scope releases | Zero or more. Each claim has a claim ID and its own description |
| Claim ID | The name of the user claim, for example email | Same character rules as the scope ID |
| Claim description | A label for the claim, shown on the consent screen | Required in English |
The form and the Central API set no maximum length for any of these values.
A scope ID is not a permission ID. payments_read is a valid scope ID, payments:read is not and the Central API rejects it. Permission IDs separate their segments with colons, see Permission.
How a scope is used
A client lists the scopes it may request. A web app or a mobile or desktop app gets this list in the Scopes section of its page, with a switch per scope for the consent screen (Client). A service app does not use scopes. It has permissions instead.
At login the client sends a subset of its scopes. auth then releases claims as follows:
- At
userinfo, it returns the claims of every granted scope, read from the user’s stored claims by claim ID. A claim the user does not have is left out.subis always present. - In the ID token, it returns only the claims the request names in the
claimsparameter. Claims are not copied into the ID token merely because a scope was granted. - On the consent screen, it shows the scope descriptions and their claim descriptions to the user before it issues the authorization code, if the client has the consent screen on.
Editing and deleting
You can change the description and add or remove claims on the edit page. The scope ID appears under the page title and cannot be edited.
Deleting a scope removes only the scope record, after a confirmation. Clients keep the ID in their scope lists, but it no longer maps to any claim. Remove the ID from those clients as well.
Next steps
- How to register a scope: the form, step by step.
- Client: where a client’s scopes are granted.
- Permission: the counterpart for service apps and for calling APIs.