Scopes

Scopes control which claims are included in the ID token and returned from the UserInfo endpoint. Autentico supports the standard OIDC core scopes.

Supported scopes

Scope	Claims included
openid	sub, iss, aud, exp, iat — required for OIDC; also triggers ID token issuance
profile	name, preferred_username, given_name, family_name, middle_name, nickname, website, gender, birthdate, profile, picture, locale, zoneinfo, updated_at (empty values omitted)
email	email, email_verified
address	address — a structured JSON object containing street_address, locality, region, postal_code, country (empty fields omitted; the entire claim is omitted if all fields are empty)
phone	phone_number, phone_number_verified
offline_access	No additional claims — enables refresh token issuance so the client can obtain new access tokens without user interaction
groups	groups — an array of group names the user belongs to
custom_claims	Every custom claim assigned to the user by an admin, merged into the ID token, access token, and UserInfo response (see Custom Claims)

Always request openid to get an ID token. Add profile and email to include those claims.

Requesting scopes

Pass scopes as a space-separated string in the authorization request:

GET /oauth2/authorize?
  response_type=code&
  client_id=my-client&
  redirect_uri=https://app.example.com/callback&
  scope=openid+profile+email+address+phone+groups&
  code_challenge=...&
  code_challenge_method=S256

The scopes are recorded on the authorization code and propagated to the token response.

Claims in tokens

ID token example with all scopes:

{
  "iss": "https://auth.example.com/oauth2",
  "sub": "a3f4e5b6-...",
  "aud": "my-client-id",
  "exp": 1700000000,
  "iat": 1699999100,
  "sid": "session-id",
  "name": "alice",
  "preferred_username": "alice",
  "given_name": "Alice",
  "family_name": "Smith",
  "email": "[email protected]",
  "email_verified": true
}

UserInfo response for an access token with profile email phone address groups scope:

{
  "sub": "a3f4e5b6-...",
  "name": "alice",
  "preferred_username": "alice",
  "email": "[email protected]",
  "email_verified": true,
  "phone_number": "+1-555-0100",
  "phone_number_verified": false,
  "address": {
    "street_address": "123 Main St",
    "locality": "Springfield",
    "region": "IL",
    "postal_code": "62704",
    "country": "US"
  },
  "groups": ["engineering", "admin"]
}

Default scopes for clients

When registering a client, set its allowed scopes via the scopes field. If omitted, the client defaults to openid profile email. The authorization request can request any subset of the client’s allowed scopes.

Custom claims are emitted only when the request includes the custom_claims scope. Omitting it is fine: the request succeeds and no custom claims are returned. Requesting it when the client’s scopes do not list custom_claims is rejected like any other disallowed scope (invalid_scope).