# On Behalf Tokens
Redirect Flow SPA
This demo SPA makes use of the on-behalf token mechanism through the redirect flow.
You may have use cases where you want to perform actions within the realm of an organization but still keep the
possibility to identify the person who initiated these actions, and this can be done through
It is important that both the person and the organization have already been connected to the app and that the organization has already requested the required permissions in the form of scopes.:
These tokens can be acquired by using the redirect flow or device flow and identifying the scope a user needs in a specific format.
# Unrequested Scopes
It may be the case that an on-behalf token is requested for a scope that was never granted before within the organization. Two scenarios are to be considered in that case:
- The user is a member: the scope won't be granted at all, the token you will receive won't possess the requested scope.
- The user is an
owner: upon organization selection, the user will be prompted to agree to give the permissions to the app.
As mentioned above, if the requesting user can't be granted the requested scope this will not trigger any error and any subsequent request with the issued token will therefore result in a permission error. Make sure to handle this scenario and to inform your user to ask the administrator to grant it in case the requested scope is not available.
# Requesting the authorisation grant
In both cases you may add an
on-behalf formatted scope to the
scope field, which takes the following form :
You may also directly specify for which organization to act on behalf of by adding the organization's
id to the scope such as:
# Exchange the grant code for an access token
If such a token was successfully requested, the following JWT payload and response is returned:
Remember that tokens issued as
on_behalf have a bearer type of
Organization, this means you should only request
scopes that are usable by organizations, scopes that are dedicated to people will be dismissed.
The role attribute is represented as integer to save space, as many servers limit the header size. Since we offer a very granular role model, this is very helpful.
This is a so-called bitfield (Wikipedia: Bitfield (opens new window)).
For this you need the list of all existing roles with the same sorting (this is provided by us via the endpoint
GET /api/v1/roles), e.g.:
The bitfield can be read with following implementation: