Scopes are used to determine which permissions each client has for a defined subject. An authenticated person must grant these permissions either to an organisation or to themselves.
We therefore distinguish between two types of bearers in a Authorization token:
Person. Scopes are used to identify the subject type for which the token is to be created.
Scopes can also be added to various audiences.
# Requested Scope Structure
This is the basic structure of a requested scope
Can be omitted or be
Per. For the client credentials flow it is also required to provide the UUID of the Organisation or Person (e.g.
It is also allowed to pass the Organization ID in the Redirect Flow or Device Flow, so that the user does not have to select an organisation again. However, this does not work for people, because it is automatically the currently logged in person.
Defines for which app the permission should be granted. For example:
The scope name is provided by each app and is given by each app.
The type of permission that is requested.
r stands for read,
w for write and
rw for read_write.
# Valid requested scopes examples
| ||By default, if no |
| ||Same as above.|
| ||The person can choose which organisation will be the bearer.|
| ||This uses a scope, that needs to be provided by |
| ||This format is required for the client credentials flow.|
| ||Enable the access token to create delegated access tokens for subsystems. See Delegating Access to Subsystems.|
When scopes are returned in
POST oauth/access_tokens, the
BEARER_TYPE will be always omitted. Instead a specific
bearer will be provided that has an
id and a
type. It can also happen that not all scopes that were requested are returned if the Bearer is not connected to the apps from the requested scopes.
# Possible Errors
Scopes are validated and following errors can occur:
| ||Multiple scopes were specified for different bearer types.|
| ||The scope your provided does not match the regex as outlined above.|
| ||The required scopes were not created as desired scopes.|
| ||The bearer types are correct, but the IDs are different (Might happen in Client Credentials Flow).|
| ||The bearer was not found or the client was not authorized by the bearer. (Might happen in Client Credentials Flow).|
| ||Bearer IDs are not allowed to be passed, the only exception is the Client Credentials Flow or to set a specific organisation.|
| ||When a scope was not granted in the parent access token. See Delegating Access to Subsystems.|
| ||A |
| ||A |
If a scope does not exist or is not applicable to the bearer type, the scope will not be part of the created access token.