> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/auth.md).

# Auth

OAuth 2.1 runtime endpoints (token exchange, revoke, introspect).

## Exchange auth code or refresh token for an access token.

> RFC 6749 token endpoint. Grants: \`authorization\_code\` (with PKCE) and \`refresh\_token\`. Refresh tokens rotate on every use — the previous refresh\_token is invalidated immediately. Request body is \`application/x-www-form-urlencoded\`, not JSON. Server-to-server integrations should use API keys, not OAuth.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Auth","description":"OAuth 2.1 runtime endpoints (token exchange, revoke, introspect)."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[],"paths":{"/oauth/token":{"post":{"tags":["Auth"],"operationId":"exchangeOAuthToken","summary":"Exchange auth code or refresh token for an access token.","description":"RFC 6749 token endpoint. Grants: `authorization_code` (with PKCE) and `refresh_token`. Refresh tokens rotate on every use — the previous refresh_token is invalidated immediately. Request body is `application/x-www-form-urlencoded`, not JSON. Server-to-server integrations should use API keys, not OAuth.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/OAuthTokenRequest"}}}},"responses":{"200":{"description":"New tokens issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenResponse"}}}},"400":{"description":"Invalid grant, unknown client, expired/reused code, or PKCE mismatch.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string","enum":["invalid_request","invalid_client","invalid_grant","unauthorized_client","unsupported_grant_type","invalid_scope"]},"error_description":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"schemas":{"OAuthTokenRequest":{"type":"object","description":"Form-encoded body per RFC 6749. Two grant types supported:\n- `authorization_code` with PKCE — for interactive auth after a user grants access.\n- `refresh_token` — to exchange a refresh token for a new access token. Refresh tokens rotate on every use; the old refresh token is invalidated.\n","required":["grant_type","client_id"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"]},"client_id":{"type":"string","description":"Your OAuth client's ID."},"client_secret":{"type":"string","description":"Confidential clients only. Public clients (SPAs, native apps) must NOT send this; they authenticate via PKCE."},"code":{"type":"string","description":"Required for `authorization_code`. The code you received at your redirect_uri."},"redirect_uri":{"type":"string","description":"Required for `authorization_code`. Must match the URI used in the authorization request."},"code_verifier":{"type":"string","description":"Required for `authorization_code` with PKCE (which is required for all interactive flows). The verifier that produced the `code_challenge` on the authorization request."},"refresh_token":{"type":"string","description":"Required for `refresh_token` grant."},"scope":{"type":"string","description":"Space-separated scopes to request. On refresh, you may request a subset of the previously granted scopes; you cannot request additional scopes."}}},"OAuthTokenResponse":{"type":"object","required":["access_token","token_type","expires_in"],"properties":{"access_token":{"type":"string"},"token_type":{"type":"string","const":"Bearer"},"expires_in":{"type":"integer","description":"Seconds until the access token expires."},"refresh_token":{"type":"string","description":"Present on `authorization_code` grant and every `refresh_token` grant (rotated)."},"scope":{"type":"string","description":"Space-separated actually-granted scopes."}}},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}
```

## Revoke an OAuth token.

> RFC 7009. Revokes either an access token or a refresh token.\
> Revoking a refresh token invalidates all access tokens issued from it. Revoking an access token does NOT invalidate its refresh token.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Auth","description":"OAuth 2.1 runtime endpoints (token exchange, revoke, introspect)."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[],"paths":{"/oauth/revoke":{"post":{"tags":["Auth"],"operationId":"revokeOAuthToken","summary":"Revoke an OAuth token.","description":"RFC 7009. Revokes either an access token or a refresh token.\nRevoking a refresh token invalidates all access tokens issued from it. Revoking an access token does NOT invalidate its refresh token.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"token_type_hint":{"type":"string","enum":["access_token","refresh_token"]},"client_id":{"type":"string"},"client_secret":{"type":"string"}}}}}},"responses":{"200":{"description":"Revoked (or the token was already invalid — the spec requires 200 either way)."}}}}}}
```

## Introspect an OAuth token.

> RFC 7662. Check whether a token is currently active and, if so, what it authorizes.\
> Requires client credentials — public clients cannot introspect.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Auth","description":"OAuth 2.1 runtime endpoints (token exchange, revoke, introspect)."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[],"paths":{"/oauth/introspect":{"post":{"tags":["Auth"],"operationId":"introspectOAuthToken","summary":"Introspect an OAuth token.","description":"RFC 7662. Check whether a token is currently active and, if so, what it authorizes.\nRequires client credentials — public clients cannot introspect.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["token","client_id","client_secret"],"properties":{"token":{"type":"string"},"token_type_hint":{"type":"string","enum":["access_token","refresh_token"]},"client_id":{"type":"string"},"client_secret":{"type":"string"}}}}}},"responses":{"200":{"description":"Introspection result. `active: false` means the token is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthIntrospectionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"schemas":{"OAuthIntrospectionResponse":{"type":"object","required":["active"],"description":"Per RFC 7662. `active` is the only guaranteed field; other fields are present when the token is valid.\n","properties":{"active":{"type":"boolean"},"scope":{"type":"string"},"client_id":{"type":"string"},"username":{"type":"string"},"exp":{"type":"integer","description":"Expiration timestamp (Unix seconds)."},"iat":{"type":"integer","description":"Issued-at timestamp."},"sub":{"type":"string","description":"The subject (user ID) for user-scoped tokens."},"aud":{"type":"string"},"token_type":{"type":"string","enum":["access_token","refresh_token"]}}},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}
```
