OAuth and OpenID Connect
Use GET {ISSUER}/.well-known/openid-configuration as the source of endpoint URLs and supported metadata. The gateway protocol routes use /api/oauth2 and do not include /v1.
Endpoint catalog
| Method | Route | Purpose |
|---|---|---|
| GET | /api/oauth2/authorize | Start an authorization interaction; browser clients normally use the hosted authorization_endpoint from discovery. |
| POST | /api/oauth2/token | Exchange authorization codes, refresh tokens, client credentials, device codes, or profile token-exchange requests. |
| 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 active public signing keys. |
| POST | /api/oauth2/register | Register a developer-owned client using an account-portal access token. |
| GET, PUT, DELETE | /api/oauth2/register/{client_id} | Read, update, or delete a developer-owned registration. |
| GET, POST | /api/oauth2/logout | Log out the current ID-token-backed session. |
| GET, POST | /api/oauth2/end-session | End the IdP session and coordinate configured front/back-channel logout. |
Token grants
grant_type | Required grant 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 |
urn:ietf:params:oauth:grant-type:token-exchange | subject_token, requested_profile_id; optional scope, pin_code |
The response uses access_token, optional refresh_token and id_token, expires_in, token_type, and optional scope.
Client authentication
Public clients send client_id without a secret. Confidential clients use their registered method: HTTP Basic or client_secret_post. 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 containing openid. Client-credentials tokens are rejected. Returned claims are filtered by granted scope: profile, email, and phone. Raha Account also checks the token's authorization version against the live client grant.
Resource indicators
Client Credentials requires a configured resource. The account directory publishes RFC 9728 protected-resource metadata; see Account directory.