Scopes and consent

What a scope is, the standard scopes and what each shares, how product scopes work, and how scopes differ from permissions.

On this page

A scope is a word an application sends when it asks to sign you in. It names a category of access that the application is asking for. You meet scopes as plain sentences on the consent screen. The tokens an application receives record which scopes were granted.

Scopes answer "what is this application allowed to see or do on my behalf". They do not answer "what am I allowed to do". That is authorization, and the two are kept apart on purpose.

The standard scopes#

Scope	Shown on the consent screen as	What it gives the application
`openid`	Confirm who you are	Confirms you are signed in and shares the account identifier the application knows you by. On its own it shares no name and no email address.
`profile`	Your name and preferences	Your display name, username, profile picture, language and time zone, and when you last changed your profile.
`email`	Your email address	Your email address, and whether you have verified it.
`offline_access`	Stay signed in	Lets the application keep working in the background and stay signed in, using a refresh token. You can end it from Connected apps in your account.
`tdaid.tenant`	Your organization	Names the organization you are signed in to on the consent screen. The `tid` and `tslug` claims do not depend on it.

openid is required on every sign-in request. Without it there is no sign-in to ask for, and the request is refused. The picture is included only when you have uploaded one. An application registered for per-application identifiers sees an identifier of its own for you in the ID token and the userinfo response, and receives no picture.

The generated Scopes reference lists every scope with its consent sentence.

Product scopes#

An application can also ask for a scope named after a product, for example the product's short name. The consent screen titles it Your followed by the scope name and access, for example Your eidos access, and says it lets the application use your permissions in that product, limited to what your role there allows.

A product scope says "this application may act with my access to that product". It does not grant any access you do not already hold there, and it never grants more than your role. See Permissions and roles.

A name is a product scope when it is lowercase letters, digits and underscores, starting with a letter, between two and 32 characters long. A scope that identity does not recognise is shown unticked.

Personal access token scopes#

Personal access tokens, which you create for scripts, use their own two scopes: one to read your own profile and one to edit it. They do not appear in sign-in. They are listed in the Scopes reference.

Who decides which scopes an application can have#

Three things limit what an application receives. The result is always the smallest of them.

What the application is registered for. An application can only ask for scopes it was registered to hold. Asking for any other scope fails with invalid_scope.
What you grant. On the consent screen you can untick the optional scopes. The authorization is completed for the requested scopes that you granted, plus openid.
What a later token asks for. A refresh can ask for fewer scopes than the family holds, never more. A token exchange narrows further: the result is limited to the subject token's scopes and the target's allowed scopes. See Delegation and token exchange.

The application should read the scope it actually received, not assume it got everything it asked for.

Scopes in tokens#

The access token carries the granted scopes as a space-separated scope claim. The ID token and the userinfo response release the profile claims that the scopes allow: the name, username, picture, language, time zone and last profile change for profile, and the email address and its verified state for email, and nothing else.

What scopes do not do#

They are not roles. Tokens carry no roles claim and there is no roles scope. Product scopes replace it. See Authorization.
They do not choose an organization. An application preselects one with tdaid_tenant, and the tokens report it in tid and tslug whenever the sign-in belongs to an organization. See Organizations.
They do not expire on their own. A scope lasts as long as the consent and the tokens behind it. See Consent.

For people who build applications#

How to ask for scopes and a resource, and what the helpers send, is on Scopes and consent in the build guide.