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 |
回包
302FounddefaultError —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).
回包
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) (可不带)
回包
200OK —application/json·AppTokenBody400OAuth error (RFC 6749 §5.2) other than invalid_client, including an empty request body (invalid_request) —application/json·AppOAuthError401invalid_client: the App ID and App Secret did not authenticate the app —application/json·AppOAuthErrordefaultError —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) (可不带)
回包
200OK —application/json·AppTokenBody400OAuth error (RFC 6749 §5.2) other than invalid_client, including an empty request body (invalid_request) —application/json·AppOAuthError401invalid_client: the App ID and App Secret did not authenticate the app —application/json·AppOAuthErrordefaultError —application/problem+json·D8Error
