Scopes and Claims

Standard OIDC scopes

Scope	Description	Returned claims
openid	Required. Indicates an OIDC authentication request.	sub (user GUID)
profile	Basic user profile information	name, given_name, family_name
email	The user's email address	email, email_verified
phone	The user's phone number	phone_number, phone_number_verified
address	The user's postal address	address object
offline_access	Request a refresh token	(enables refresh tokens)

API scope

Scope	Description	Usage
api	Access to the service API	Managing users, sessions, 2FA

M2M (Machine-to-Machine) only

The api scope is intended exclusively for the Client Credentials flow (service-to-service communication). User tokens obtained via the Authorization Code Flow cannot access the API endpoints.

The /api/* service endpoints require:

1. A token obtained via the Client Credentials flow
2. The api scope
3. A token whose sub equals the client_id (which is a property of Client Credentials flow tokens)

User tokens (Authorization Code Flow) do not meet this condition, and therefore cannot call the /api/* management endpoints.

Claims overview

Claims in the ID token

The ID token always contains:

Claim	Description	Example
iss	Token issuer	https://your-sso-domain.com/
sub	User identifier (GUID)	550e8400-e29b-41d4-a716-446655440000
aud	Intended audience (client_id)	my-app
exp	Expiration time (Unix timestamp)	1704067200
iat	Issued-at time (Unix timestamp)	1704065400
nonce	Value for replay protection	abc123

Profile claims (scope: profile)

Claim	Description	Example
name	Full name	Jan Novák
given_name	First name	Jan
family_name	Last name	Novák

Email claims (scope: email)

Claim	Description	Example
email	Email address	jan@example.com
email_verified	Whether the email is verified	true

Phone claims (scope: phone)

Claim	Description	Example
phone_number	Phone number	+420123456789
phone_number_verified	Whether the phone is verified	true

Address claims (scope: address)

Claim	Description	Example
address.street_address	Street and number	Hlavní 123
address.locality	City	Praha
address.postal_code	Postal code	11000

Other claims

Claim	Description	Possible values
role	The user's role	User, Cashier, Administrator, SuperAdministrator

The role claim is always present

The role claim is emitted always – in both the access token and the ID token – regardless of the requested scopes. There is no roles scope that would control this behavior.

Example: Decoded ID token

{
  "iss": "https://your-sso-domain.com/",
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "aud": "my-app",
  "exp": 1704067200,
  "iat": 1704065400,
  "nonce": "abc123",
  "name": "Jan Novák",
  "given_name": "Jan",
  "family_name": "Novák",
  "email": "jan@example.com",
  "email_verified": true,
  "role": "User"
}

Example: UserInfo response

Request:

curl https://your-sso-domain.com/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Jan Novák",
  "given_name": "Jan",
  "family_name": "Novák",
  "email": "jan@example.com",
  "email_verified": true,
  "phone_number": "+420123456789",
  "phone_number_verified": true,
  "address": {
    "street_address": "Hlavní 123",
    "locality": "Praha",
    "postal_code": "11000"
  },
  "role": "User"
}

Requesting scopes

Include the requested scopes in the authorization request:

scope=openid profile email offline_access

Best practice

Request only the scopes your application actually needs. Users are more likely to grant consent when fewer permissions are requested.