OpenMax
Free Trial

Apps API · Authentication

Authentication: 4 endpoints

← All groups

GET /api/v1/apps/authorize

App authorization endpoint

Scope: No scope required · Called with: none · operationId: authorize-app-redirect

The public OAuth 2.0 authorization endpoint of Workspace apps (issuer + /api/v1/apps/authorize). It reads no credential and checks nothing: it answers 302 to the Workspace authorization page with the query unchanged; the page checks the request under the member's own session and sends the browser back to the app's redirect_uri (with a code, or an OAuth error). Requests not trusted to name the app's own callback (unknown client_id, mismatched redirect_uri) are shown on the page, never redirected. 400 when the query exceeds 4 KiB. Parameters (RFC 6749 §4.1.1, RFC 7636 §4.3, OpenID Connect): response_type=code (required); client_id = the App ID, app_... (required); redirect_uri, byte for byte the manifest redirect_uri of the installed version (required); state, 1-512 visible ASCII characters, echoed back unchanged and never stored (required); code_challenge, the 43-character base64url S256 challenge of the app's code_verifier (required); code_challenge_method=S256 (required; plain is refused); scope, space-delimited, optional, only narrows the installation's granted scopes (openid is accepted and ignored); nonce, at most 256 visible ASCII characters, echoed in the id_token (optional); prompt, accepted and without effect: authorization never needs a signed-in member's interaction, so prompt=none is always satisfied (without a session the answer is login_required whatever the prompt).

Parameters

Name In Type Required Description
response_type query string code
client_id query string The App ID (app_...)
redirect_uri query string The app's registered redirect_uri
state query string The app's anti-CSRF value
code_challenge query string PKCE S256 challenge
code_challenge_method query string S256
scope query string Optional scope narrowing
nonce query string Optional id_token nonce
prompt query string Optional OpenID Connect prompt

Responses

  • 302 Found
  • default Error — application/problem+json · D8Error

GET /api/v1/apps/jwks

Get the app token key set

Scope: No scope required · Called with: none · operationId: get-app-jwks

Public JWK Set (RFC 7517) of the keys that sign app id_tokens and access tokens; select the key by the token's kid. During a key rotation the previous key stays listed until it is retired. Public, plain JSON (no envelope).

Responses

  • 200 OK — application/json · JWKSet
  • default Error — application/problem+json · D8Error

POST /api/v1/apps/token

Exchange an app code for tokens

Scope: No scope required · Called with: appClient · operationId: exchange-app-token

OAuth 2.0 token endpoint for an app's backend (RFC 6749; form-encoded, JSON also accepted). The client authenticates with its App ID and App Secret only — app_id / app_secret (or client_id / client_secret) in the body, or HTTP Basic; a user session token or personal access token is never accepted (invalid_client). grant_type=authorization_code redeems an authorization code from the authorization endpoint (GET /api/v1/apps/authorize; code, redirect_uri exactly as in the authorization request, and code_verifier — required, PKCE S256, RFC 7636: a missing or malformed code_verifier is invalid_request and leaves the code usable, a mismatched one is invalid_grant and burns the code) once, within 60 seconds, while the installation is still active at the code's epoch and the member still active. The answer is {access_token, token_type: Bearer, expires_in: 900, id_token, scope, user: {member_id, org_id, name, org_role, email?}}; access_token is a JWT signed with the app token key (sub = member_id) that the app sends as Authorization: Bearer to /api/v1/*, where it is limited to its scopes and the member's own permissions. grant_type=refresh_token (only grants carrying offline_access get a refresh_token, 30 days) rotates the refresh token on every use; replaying a rotated one revokes the whole chain, except within 30 seconds of its rotation while no token rotated from it has been used or revoked (a concurrent or retried refresh), which gets another refresh token of the same grant; each refresh re-checks the installation and the member and never widens the scopes (an optional scope narrows them). Errors use the RFC 6749 §5.2 body: invalid_request, invalid_client (401), invalid_grant, invalid_scope, unsupported_grant_type.

Parameters

Name In Type Required Description
Authorization header string Optional HTTP Basic client authentication (App ID: App Secret)
Content-Type header string

Request body

application/x-www-form-urlencoded · string (binary) (optional)

Responses

  • 200 OK — application/json · AppTokenBody
  • 400 OAuth error (RFC 6749 §5.2) other than invalid_client, including an empty request body (invalid_request) — application/json · AppOAuthError
  • 401 invalid_client: the App ID and App Secret did not authenticate the app — application/json · AppOAuthError
  • default Error — application/problem+json · D8Error

POST /api/v1/apps/token/revoke

Revoke an app refresh token

Scope: No scope required · Called with: appClient · operationId: revoke-app-token

OAuth 2.0 token revocation (RFC 7009) for an app's backend; same client authentication as exchange-app-token (App ID and App Secret only). token is a refresh token of this app: it and its whole rotation chain are revoked. An unknown token answers 200 as well. Access tokens are not revoked one by one (unsupported_token_type): they expire within 15 minutes, or at once when the installation is suspended, uninstalled or narrowed. Errors use the RFC 6749 §5.2 body (invalid_client 401, invalid_request).

Parameters

Name In Type Required Description
Authorization header string Optional HTTP Basic client authentication (App ID: App Secret)
Content-Type header string

Request body

application/x-www-form-urlencoded · string (binary) (optional)

Responses

  • 200 OK — application/json · AppTokenBody
  • 400 OAuth error (RFC 6749 §5.2) other than invalid_client, including an empty request body (invalid_request) — application/json · AppOAuthError
  • 401 invalid_client: the App ID and App Secret did not authenticate the app — application/json · AppOAuthError
  • default Error — application/problem+json · D8Error