OAuth and OpenID Connect
Use GET {ISSUER}/.well-known/openid-configuration as the source of endpoint URLs and supported metadata. Protocol routes use /api/oauth2 and do not include /v1.
Endpoint catalog
| Method | Route | Purpose |
|---|---|---|
| GET | /api/oauth2/authorize | Start sign-in. Browser clients should use the hosted authorization_endpoint from discovery. |
| POST | /api/oauth2/token | Exchange authorization codes, refresh tokens, client credentials, or device codes for tokens. |
| POST | /api/oauth2/device_authorization | Create device and user codes. |
| GET, POST | /api/oauth2/userinfo | Return claims approved for a delegated OpenID access token. |
| POST | /api/oauth2/introspect | Introspect a token as its authenticated confidential client. |
| POST | /api/oauth2/revoke | Revoke a token as its authenticated confidential client. |
| GET | /api/oauth2/jwks | Return the public signing keys. |
| GET, POST | /api/oauth2/logout | Sign out the session behind an ID token. |
| GET, POST | /api/oauth2/end-session | End the Raha Account session and coordinate front- and back-channel logout. See logout. |
Token grants
grant_type | Required fields |
|---|---|
authorization_code | code, redirect_uri, code_verifier |
refresh_token | refresh_token; optional reduced scope |
client_credentials | resource; optional scope |
urn:ietf:params:oauth:grant-type:device_code | device_code |
The response contains access_token, token_type, expires_in, and, when applicable, refresh_token, id_token, and scope.
Refresh tokens are issued only when the user consents to offline_access. Refreshing with a reduced scope returns an access token limited to that subset.
Client authentication
Public clients send client_id without a secret and rely on PKCE. Confidential clients use their registered method:
- HTTP Basic:
Authorization: Basic base64(client_id:client_secret). client_secret_post:client_idandclient_secretas form fields.
Do not send both methods in one request. Introspection and revocation authenticate the calling client; the token being inspected or revoked does not authenticate the request.
UserInfo
UserInfo requires a delegated access token that includes the openid scope. Client-credentials tokens are rejected. Returned claims depend on the granted scopes:
| Scope | Claims |
|---|---|
openid | sub |
profile | Name and profile picture claims |
email | email, email_verified |
phone | phone_number, phone_number_verified |
If the user revokes your application or its access changes, UserInfo rejects tokens issued before the change.
Signing keys
Verify tokens with the keys published at the discovered jwks_uri. Cache the JWKS according to its HTTP caching headers and refetch it when a token references an unknown kid. Keys rotate over time, and previous keys stay published while tokens signed with them are still valid.
Resource indicators
Client Credentials requires a resource that has been granted to your application. Protected resources publish RFC 9728 metadata describing their resource identifier and scopes; see Account directory.