The contract behind the code.

GET /authorize

Authorization Code flow with mandatory PKCE (S256) — no client secrets exist. Details per parameter:

Scopes are the four OIDC scopes plus declared AXUS permission keys. Unprefixed keys use system context; use app:<app AUID>:<permission key> for another app’s context. Parameter wildcards require declaration support; bare *requests all permissions the caller holds in one context. Legacy prefix wildcards are rejected. The user reviews engine-provided descriptions on the consent screen. See permission scopes and contexts.

A scope must appear in only one list. Optional scopes can include OIDC scopes; conditional scopes support AXUS permissions only. If scope is omitted, it defaults to openid. Pass optional_scope and conditional_scopeas additional authorization parameters when using an OIDC library.

{
  "scope": "openid profile app:5:posts.read",
  "optional_scope": "app:5:posts.write",
  "conditional_scope": "app:5:posts.moderate"
}

Replace 5 with the declaration owner’s AUID and use declared keys. Available optional scopes start checked. Conditional permissions are required when held and cannot be toggled off; unavailable optional and conditional permissions are omitted. Availability is checked again at consent submission.

Authorization outcomes

Validate state before handling success or errors. Missing mandatory access issues no code or tokens and leaves the AXUS ID session active. Interactive requests show the missing permissions and let the user switch accounts or return to the app; returning sends the error callback. prompt=none returns the error immediately without UI. Declined optional scopes prompt again when requested later. Use prompt=consent to review previously approved choices. See the flow walkthrough.

POST /oauth/token

Accepts form-encoded or JSON bodies. client_id can travel in the body, as the username half of Basic auth (password ignored for library compatibility), or as auid.

curl --request POST 'https://axusid-website.vercel.app/oauth/token' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_AUID' \
  --data-urlencode 'redirect_uri=https://app.example/auth/callback' \
  --data-urlencode 'code=AUTHORIZATION_CODE' \
  --data-urlencode 'code_verifier=ORIGINAL_VERIFIER'

Failure codes, all JSON with error and error_description:

The token response

{
  "access_token": "axid_at_…",
  "token_type": "Bearer",
  "expires_in": 43200,
  "id_token": "eyJhbG…",
  "axus_access_token": "…"
}

Refresh tokens are bound to their client. Request offline_access only for continued API access; serialize refreshes and save each replacement atomically.

GET /oauth/userinfo

Authorization: Bearer <access_token>, GET or POST. The token must carry the openid scope or you get invalid_token (401, with WWW-Authenticate). Claims are filtered by granted scope — you never see more than the user approved:

GET /gravatar/<email_hash>

Hash the trimmed, lowercase synthetic email (<auid>@amail.com) using MD5 or SHA-256. This public endpoint returns the current default variation’s avatar as a square JPEG. An optional .jpg suffix is accepted. Responses cache for five minutes and allow cross-origin reads.

Accounts become available after signing in through this provider. Missing accounts or avatars use the requested default; service failures return an uncached 503.

https://axusid-website.vercel.app/gravatar/<email_hash>?s=128&d=404

POST /oauth/revoke

Body: token (required), token_type_hint (access_token or refresh_token, optional — both kinds are tried). Revoking any token ends the whole authorization: the app’s native token is revoked at the engine and its remaining tokens go with it. The user’s own session is untouched. Unknown tokens still return 200.

curl --request POST 'https://axusid-website.vercel.app/oauth/introspect' \
  --data-urlencode 'client_id=YOUR_AUID' \
  --data-urlencode 'token=ACCESS_TOKEN'

{
  "active": true,
  "scope": "openid profile",
  "client_id": "YOUR_AUID",
  "sub": "USER_AUID",
  "token_type": "Bearer",
  "exp": 2000000000,
  "iss": "https://axusid-website.vercel.app"
}

POST /oauth/graphql

Send a JSON GraphQL request with Authorization: Bearer <access_token>. The proxy resolves the OAuth token to the authorization’s native AXUS token and forwards the request to the engine, limited by granted permissions (discovery: axus_graphql_proxy_endpoint). The separate axus_access_token is a server-side credential for direct native calls — not an identifier, not an ID token.

Refresh an authorization

Request offline_access during authorization to receive a refresh token. Each successful refresh returns a replacement. Tokens are long-lived but can be revoked; do not assume the connection will last indefinitely.

curl --request POST 'https://axusid-website.vercel.app/oauth/token' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=YOUR_AUID' \
  --data-urlencode 'refresh_token=CURRENT_REFRESH_TOKEN'