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
email	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}