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

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": "alice@example.com",
  "email_verified": true
}

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

{
  "sub": "a3f4e5b6-...",
  "name": "alice",
  "preferred_username": "alice",
  "email": "alice@example.com",
  "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.