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 withorg:me.email:read),nonce,iat,exp. org_roleis for reference only and is not platform authorization; permissions inside entries are up to you, based on the bound account.access_tokenis only used asAuthorization: Bearerfor/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 unknownkid, 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., withrequest_idandserver_timeat the top level (see the sample below). - 401: the token is invalid (expired, installation disabled / uninstalled / narrowed, member left) → re-authorize.
- 403:
org:me:readnot 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).
