OpenMax
免费试用

Apps API · Authentication

Authentication: 4 个接口

← 全部分组

GET /api/v1/apps/authorize

App authorization endpoint

权限(scope): 不需要 scope · 调用方式: 无 · 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).

参数

名字 位置 类型 必填 说明
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

回包

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

GET /api/v1/apps/jwks

Get the app token key set

权限(scope): 不需要 scope · 调用方式: 无 · 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).

回包

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

POST /api/v1/apps/token

Exchange an app code for tokens

权限(scope): 不需要 scope · 调用方式: 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.

参数

名字 位置 类型 必填 说明
Authorization header string Optional HTTP Basic client authentication (App ID: App Secret)
Content-Type header string

请求体

application/x-www-form-urlencoded · string (binary) (可不带)

回包

  • 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): 不需要 scope · 调用方式: 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).

参数

名字 位置 类型 必填 说明
Authorization header string Optional HTTP Basic client authentication (App ID: App Secret)
Content-Type header string

请求体

application/x-www-form-urlencoded · string (binary) (可不带)

回包

  • 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