This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.

Reserve scopes starting with `supertokens.`

This is just a proposal so far, it hasn't been accepted and needs further discussion.

Context and Problem Statement#

When creating scopes we can choose what to allow and/or reserve for special use

Chosen option: Reserve some scopes (scopes starting with supertokens. + openid), because

Some scopes we've decided to reserve:

openid: this scope will add the id token to the token response. should be always allowed for all clients
supertokens.profile: access to email address (+ verification status), phone number and third party provider information
supertokens.roles: access to role information
supertokens.permissions: access to permission information

Based on the above scopes we will:

Add information mainly into the id token
Make this information available through the access token calling a user info endpoint
Not add these to the access token (although we will allow that to be customizable)
Do not add any information outside of the user id (and sessionHandle) without an appropriate scope, since adding PII should always be opt-in.
The main information content of the access token is contained in the scopes granted: these should be the main source of information when deciding if an operation is allowed or not. As an example: the user has an admin role, so their sessions can be used to delete users but this is not something they want to do through the forum client app. Keep in mind, that the client applications are usually not first-party, so permissions have to be carefully managed (e.g.: to mitigate a possible XSS in the forum app, even if we are assuming the app devs of the forum are not malicious).

Future-proof: If we require them in the future we can be sure noone conflicts with it

Shouldn't block any usecase - when setting up, they can just choose a different prefix

Added docs (but fairly minimal)

Very easy to communicate

Can create problems if we need to use them ourselves