OpenMax
Free Trial

Sign-in endpoints (authorize / token / me)

Parameters and responses of the three sign-in endpoints.

Per-endpoint reference pages will replace this page once the platform publishes its OpenAPI spec. For the flow and runnable code, see the Sign-in tutorial.

authorize

GET {issuer}/api/v1/apps/authorize (public endpoint; the query is passed as-is to the authorization page; a query over 4 KiB returns 400)

Parameter Requirement Description
response_type Required Always code
client_id Required App ID (app_…)
redirect_uri Required Must be byte-for-byte identical to the redirect_uri registered in the installed version's manifest
state Required 1–512 visible ASCII characters, returned as-is, not stored by the platform. Use an unguessable random value; do not put the return path or other data in it
code_challenge Required BASE64URL(SHA256(code_verifier)), 43 characters
code_challenge_method Required Must be S256 (plain is rejected)
nonce Send it Optional on the platform side (≤256 visible ASCII), written as-is into the id_token's nonce. Send it and check it in the callback to prevent id_token replay
scope Optional Space-separated; can only narrow the scopes approved at install (exceeding them returns invalid_scope); omitted = all approved scopes; openid is accepted but ignored
prompt Optional Accepted but has no effect: authorization never requires member interaction

Any other unknown parameters (login_hint, ui_locales, claims, etc.) are ignored without error.

Callback (GET {redirect_uri}?…): on success code, state, iss; on failure error, error_description, iss, plus state only when the request's state was valid (an invalid state is itself the error being reported). iss is present on failure too, so check it before reading error (RFC 9207). How to handle each step is in Sign-in.

token

POST {issuer}/api/v1/apps/token: application/x-www-form-urlencoded (JSON also accepted). Client authentication only accepts App ID + App Secret: client_id / client_secret in the body (or the aliases app_id / app_secret), or HTTP Basic. Errors follow RFC 6749 §5.2.

{
  "access_token": "eyJ…",          // JWT (typ at+jwt), sub = member_id, 15 minutes
  "token_type": "Bearer",
  "expires_in": 900,
  "id_token": "eyJ…",              // typ JWT, RS256
  "scope": "org:me:read org:me.email:read",
  "refresh_token": "cwrt_…",       // Only when the grant includes offline_access
  "user": { "member_id": "…", "org_id": "…", "name": "…", "org_role": "member", "email": "…" }
}
  • id_token claims: iss, aud (App ID), sub = member_id, member_id, org_id, name, org_role, email (only with org:me.email:read), nonce, iat, exp.
  • org_role is for reference only and is not platform authorization; permissions inside entries are up to you, based on the bound account.
  • access_token is only used as Authorization: Bearer for /api/v1/*; the id_token cannot be used as a Bearer token.
  • Refresh (requires offline_access): grant_type=refresh_token, valid for 30 days. Every refresh rotates the token, so you must save the new refresh_token; replaying an old one revokes the whole chain (except concurrent requests / retries within 30 seconds of rotation). Every refresh re-checks the installation and membership status, and scopes can only narrow.
  • Revocation: POST {issuer}/api/v1/apps/token/revoke (RFC 7009, only accepts refresh_token, revoking the whole chain). access_token is not revoked individually and expires naturally within 15 minutes; it becomes invalid immediately when the installation is disabled, uninstalled, or its scopes are narrowed (other replicas within 30 seconds at most).
  • JWKS is public, Cache-Control: max-age=300. When you see an unknown kid, fetch it again (rate-limit this); old keys are still listed during rotation.

me

GET {issuer}/api/v1/me, Authorization: Bearer <access_token>, requires org:me:read.

  • 200: the token is valid, this person is still a member of the organization, and the installation is still usable. The fields are wrapped in data: data.member_id, data.org_id, data.org_name, data.display_name, data.role.slug (org-owner / org-admin / org-member), etc., with request_id and server_time at the top level (see the sample below).
  • 401: the token is invalid (expired, installation disabled / uninstalled / narrowed, member left) → re-authorize.
  • 403: org:me:read not approved → fix the scopes in the manifest.
{
  "data": { "member_id": "…", "org_id": "…", "org_name": "…", "display_name": "…", "role": { "slug": "org-member" } },
  "request_id": "…",
  "server_time": "…"
}

Apps that only need to confirm identity at sign-in can discard the access_token after verifying the id_token. Note: a 200 from /api/v1/me only means "still valid right now"; it does not extend anything (see the next section).