Scopes & Claims

Scopes control what information your application can access. Claims are the individual pieces of data returned in tokens and from the UserInfo endpoint.

Available Scopes

Scope	Required	Description
`openid`	Yes (for OIDC)	Enables OpenID Connect — returns an ID token with `sub` claim
`profile`	No	Access to `name` and `picture` claims
`email`	No	Access to `email` and `email_verified` claims

Claims Reference

Always Included (in access tokens)

Claim	Type	Description
`iss`	string	Issuer URL (`https://aero2.dev`)
`sub`	string	User ID (UUID)
`aud`	string	Audience (client ID or API identifier)
`exp`	number	Expiration time (Unix timestamp)
`iat`	number	Issued at time (Unix timestamp)
`jti`	string	Unique token identifier
`token_use`	string	Token type: `access`, `id`, or `session`
`scope`	string	Granted scopes

ID Token Additional Claims

Claim	Scope	Type	Description
`nonce`	`openid`	string	Value from authorization request
`auth_time`	`openid`	number	Time of authentication (Unix timestamp)
`email`	`email`	string	User's email address
`email_verified`	`email`	boolean	Whether email is verified
`name`	`profile`	string	User's display name
`picture`	`profile`	string	URL to profile image

UserInfo Endpoint Claims

The /oauth2/userinfo endpoint returns claims based on granted scopes:

# With scope "openid profile email"
curl https://aero2.dev/oauth2/userinfo \
  -H "Authorization: Bearer <access_token>"

{
  "sub": "user-uuid",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "email_verified": true,
  "picture": "https://avatars.githubusercontent.com/u/12345"
}

Requesting Scopes

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

GET /oauth2/authorize
  ?scope=openid+profile+email
  &...