---
title: "Exchange authorization code for tokens"
method: POST
path: "/oauth2/token"
tags: ["OAuth Provider"]
---

# Exchange authorization code for tokens

`POST /oauth2/token`

OAuth 2.0 Token Endpoint (RFC 6749 Section 4.1.3).

Exchanges an authorization code, client credentials, or refresh token for access tokens.

**Grant Types:**
- `authorization_code`: Exchange auth code for tokens (user-based)
- `client_credentials`: Get tokens for machine-to-machine auth
- `refresh_token`: Get new access token using refresh token

For **`client_credentials`**, access tokens represent the **OAuth app creator** (the user who registered the client). The JWT may encode **`userId === client_id`**; the **Node API gateway** resolves the creator (**`createdBy`** claim or OAuth app lookup) — see **OAuth Provider** tag.

**Client Authentication:**
Can be provided via:
- HTTP Basic auth: `Authorization: Basic base64(client_id:client_secret)`
- Request body: `client_id` and `client_secret` parameters

**PKCE Verification:**
If authorization used PKCE, the `code_verifier` must be provided and will be
verified against the stored code challenge.

## Request body

- OAuthTokenRequest — OAuth 2.0 Token Request (RFC 6749 Section 4.1.3). Request body for exchanging authorization code or credentials for tokens.
  - `grant_type` 'authorization_code' | 'client_credentials' | 'refresh_token', required — OAuth grant type: - `authorization_code`: Exchange auth code for tokens - `client_credentials`: Machine-to-machine auth - `refresh_token`: Get new access token using refresh token
  - `code` string — Authorization code (required for authorization_code grant)
  - `redirect_uri` string, uri — Redirect URI (required for authorization_code grant)
  - `client_id` string — Client ID (can also be sent via Basic auth header)
  - `client_secret` string — Client secret (can also be sent via Basic auth header)
  - `refresh_token` string — Refresh token (required for refresh_token grant)
  - `scope` string — Requested scopes (optional, defaults to original grant scopes)
  - `code_verifier` string — PKCE code verifier (RFC 7636). Required if code_challenge was used. Must be 43-128 characters from [A-Za-z0-9-._~]

## Response `200`

Tokens issued successfully

- OAuthTokenResponse — OAuth 2.0 Token Response (RFC 6749 Section 5.1). Contains the access token and optional refresh/ID tokens.
  - `access_token` string — The access token for API requests
  - `token_type` string — Token type (always "Bearer")
  - `expires_in` integer — Access token lifetime in seconds
  - `refresh_token` string — Refresh token for obtaining new access tokens
  - `scope` string — Granted scopes (may differ from requested)
  - `id_token` string — OpenID Connect ID token (JWT) if openid scope was requested

## Other responses

- `400` — Invalid request (missing parameters, invalid code, etc.)
- `401` — Client authentication failed
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)