Scopes & UserInfo

Four scopes exist. There is no offline_access — refresh tokens are always issued with the code exchange.

Scope	Unlocks
`openid`	Authentication itself; conventional to request, adds no extra claims
`profile`	`name`, `picture` (when the user has set them)
`email`	`email`, `email_verified` (only if the account has an email)
`phone`	`phone_number`, `phone_number_verified` (only if the account has a phone)

Requesting scopes

Ask at /oauth/authorize; the server checks your list is a subset of the client's registered allowed_scopes — anything beyond that is rejected before login even starts:

?scope=openid%20profile%20email

What userinfo returns per scope

GET /oauth/userinfo
Authorization: Bearer <access_token>

The response is raw JSON (not the envelope). Claims are added only for scopes on the token, and only when the user actually has that attribute — absent claims are omitted, never null.

Scope	Claims added
(always)	`sub`
`profile`	`name`, `picture`
`email`	`email`, `email_verified`
`phone`	`phone_number`, `phone_number_verified`

Examples

openid profile email:

{
  "sub": "b3f1c92e-4d5a-4f6b-8a7c-9e0d1f2a3b4c",
  "name": "Amina Juma",
  "email": "amina@example.com",
  "email_verified": true
}

openid phone only:

{
  "sub": "b3f1c92e-4d5a-4f6b-8a7c-9e0d1f2a3b4c",
  "phone_number": "+255712345678",
  "phone_number_verified": true
}

A minimal account with no profile data and only openid granted returns just:

{ "sub": "b3f1c92e-4d5a-4f6b-8a7c-9e0d1f2a3b4c" }

Error — missing/expired/revoked bearer token:

{ "success": false, "message": "invalid or expired access token" }

(401 status.)

Consent & scope expansion

Consent records are additive. If the user previously approved openid profile and the app now asks for email too, /oauth/authorize routes them through the consent screen again to approve the expanded set. Declining yields error=access_denied on the callback.

Users can revoke any grant from the Cockpit (DELETE /connections/{client_id}), which also kills all live tokens for that app instantly.

Design guidance

Ask for the minimum: most apps need nothing more than openid profile email
Key users by sub — emails and phones can change or be absent entirely
Handle omitted claims gracefully (name may be unset; accounts can be phone-only)

Tokens & Claims Sessions & Cross-App SSO