Scope
The scope of an access token is a list of space-delimited strings (scope values) associated with the access token. Scope values can be viewed as permissions. The scope attained affects which protected resources the client is allowed to get access to using the access token. The protected resources are typically available on resource servers, which are implemented according to the OAuth bearer token usage specification (RFC 6750). For each request to a resource server, it verifies that the scope for the access token is sufficient for accessing the protected resource.
When the client initiates an authorization request, it requests the scope it needs using the scope parameter for the /authorize endpoint. The user will typically get the chance to allow or disallow that the client gets access to the resources protected by the scope values in a separate user dialog.
The scope value openid dictates the use of OpenID Connect over OAuth 2.0. When this scope value is given, the return value from the call which generates tokens based on the one-time authorization code also returns an ID token. The ID token is a signed JSON Web Token (JWT) containing, among other things, iss (Issuer Identifier for the issuer of the response) and sub (Subject identifier, in this case the user's ID). The user ID is a required part of the path for some of the resource server endpoints listed below.
The following tables constitute a comprehensive list of available scope values within CONNECT and the resource server endpoints they belong to. Note that services that implement custom resource servers can get additional custom scope values configured for their clients.
OAuth resources
More details about these scope values can be found in the OpenID Connect Core specification
Scope value | Description | Endpoint |
---|---|---|
openid | Requesting this scope value results in an ID token being returned when exchanging your authorization code for an access/refresh token pair. | POST /oauth/token |
profile | Basic user information. Claims: name and locale. Additional claims are not supported yet. | GET /oauth/userinfo |
The user's preferred email address. Claims: email and email_verified. | GET /oauth/userinfo | |
address | The user's known postal address. Claims: address. Not supported yet. | GET /oauth/userinfo |
phone | The user's preferred phone number. Claims: phone_number and phone_number_verified. | GET /oauth/userinfo |
User and rights management resources
All requests requiring a user ID must contain the user ID that the bearer token is issued on behalf of. This ID is provided in the ID token, or in the response of a /userinfo or /id/users/me request.
Scope value | Description | Endpoint |
---|---|---|
id.user.read | Read access to basic user information. | GET /id/users/me GET /id/users/{userId} |
id.user.write | Update/Write access to basic user information. Not available for public clients. | PUT /id/users/me PUT /id/users/{userId} |
id.user.email.read | Read access to all registered user email addresses. | GET /id/users/{userId}/mails GET /id/users/{userId}/mails/{mailId} |
id.user.phone.read | Read access to all registered user phone numbers. | GET /id/users/{userId}/phones GET /id/users/{userId}/phones/{phoneId} |
id.user.right.read | Read access to all registered user rights. | GET /id/users/{userId}/rights GET /id/users/{userId}/rights/{rightId} |
id.user.right.use | Record usage on a right to indicate that the right is being consumed. Not available for public clients. | POST /id/users/{userId}/rights/{rightId}/usage |
id.user.sub.read | Read access to all registered user subscriptions. | GET /id/users/{userId}/subs GET /id/users/{userId}/subs/{subId} |
id.user.account.read | Read access to all registered user accounts. | GET /id/users/{userId}/accounts GET /id/users/{userId}/accounts/{accountId} |
Payment resources
Scope value | Description | Endpoint |
---|---|---|
payment.transactions.read | Read access to a one-time transaction. | GET /transactions/{transactionId} GET /users/{connectId}/transaction |
payment.transactions.write | Update/Write access to a one-time transaction. | POST /transactions PUT /transactions/{transactionId} |
payment.agreements.read | Read access to a recurring charging agreement. | GET /agreements, GET /agreements/{agreementId} GET /users/{connectId}/agreements |
payment.agreements.write | Update/Write access to a recurring charging agreement. | POST /agreements PUT /agreements/{agreementId} |