> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rydhm.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rydhm.ai/_mcp/server.

# Swap a one-time code for the workspace's key

POST https://api.rydhm.ai/v1/oauth/token
Content-Type: application/json

Your server, after Rydhm sends the admin back to your `redirect_uri` with `code` and `state` (check `state`). Form-encoded or JSON. The client authenticates with `client_secret` (in the body, or HTTP Basic) when the app has one, and always with the PKCE `code_verifier`. A code works once, for 10 minutes; presented again, the connection it made is revoked. Connecting the same app to the same workspace again replaces the earlier connection. Errors are RFC 6749: `invalid_request`, `invalid_client` (401), `invalid_grant`, `unsupported_grant_type`.

No API key: your app authenticates with its client id and secret (in the body, or HTTP Basic) and the PKCE code_verifier. Rate limited per address and per app.

Reference: https://docs.rydhm.ai/api-reference/connect/exchange-code

## Request

### Body (application/json)

This endpoint expects an object.

- `grant_type` (enum, required)
  - Allowed values: `authorization_code`
- `code` (string, required) — From the redirect.
- `redirect_uri` (string, required) — Exactly the address the connection started with.
- `client_id` (string, required) — `rydhm_app_…` (or in HTTP Basic).
- `code_verifier` (string, required) — The PKCE verifier whose S256 challenge started the connection (43–128 characters).
- `client_secret` (string, optional) — `rydhm_cs_…`, when the app has one (or in HTTP Basic).

## Response

### 200

OK

- `access_token` (string, required) — `rydhm_live_…`: send it as Bearer on every call for this workspace.
- `token_type` (enum, required)
  - Allowed values: `bearer`
- `scope` (string, required) — The granted scopes, space-separated.
- `workspace` (OAuthTokenWorkspace, required)
- `connection_id` (string, required)
- `webhook_id` (string, required, nullable)
- `webhook_secret` (string, required, nullable)
- `webhook_error` (string, optional) — Why no webhook endpoint could be added (the connection works anyway).

## Errors

### 400 Bad Request Error

`invalid_request`, `invalid_grant`, `unsupported_grant_type` (`error` and `error_description`).

- `statusCode` (integer, required)
- `message` (string, required)
- `error` (string, optional) — A stable code such as insufficient_scope, expert_not_allowed, rate_limited, plan_limit, payment_required.
- `code` (string, optional) — The stable code on the refusals that carry it here instead of in `error`: stale_edit (409 on an expert save).
- `requestId` (string, optional) — The X-Request-Id of the call, to quote to support.
- `upgradeHint` (ErrorUpgradeHint, optional) — On 402 payment_required and 403 plan_limit: what fixes it.
- `requiredScopes` (list of string, optional) — On 403 insufficient_scope: what the route needs.
- `missingScopes` (list of string, optional)
- `retryAfterSeconds` (integer, optional) — On 429: how long to wait.
- `retryAt` (datetime, optional, nullable)
- `timeZone` (string, optional, nullable)
- `localTime` (string, optional, nullable)
- `state` (string, optional, nullable)
- `exceptionsAllowed` (boolean, optional) — On 400 outside_calling_hours: whether `callingHoursException` may be sent.

### 401 Unauthorized Error

`invalid_client`: unknown client_id, or a wrong or missing client secret.

- `statusCode` (integer, required)
- `message` (string, required)
- `error` (string, optional) — A stable code such as insufficient_scope, expert_not_allowed, rate_limited, plan_limit, payment_required.
- `code` (string, optional) — The stable code on the refusals that carry it here instead of in `error`: stale_edit (409 on an expert save).
- `requestId` (string, optional) — The X-Request-Id of the call, to quote to support.
- `upgradeHint` (ErrorUpgradeHint, optional) — On 402 payment_required and 403 plan_limit: what fixes it.
- `requiredScopes` (list of string, optional) — On 403 insufficient_scope: what the route needs.
- `missingScopes` (list of string, optional)
- `retryAfterSeconds` (integer, optional) — On 429: how long to wait.
- `retryAt` (datetime, optional, nullable)
- `timeZone` (string, optional, nullable)
- `localTime` (string, optional, nullable)
- `state` (string, optional, nullable)
- `exceptionsAllowed` (boolean, optional) — On 400 outside_calling_hours: whether `callingHoursException` may be sent.

### 429 Too Many Requests Error

Rate limited; wait Retry-After seconds.

- `statusCode` (integer, required)
- `message` (string, required)
- `error` (string, optional) — A stable code such as insufficient_scope, expert_not_allowed, rate_limited, plan_limit, payment_required.
- `code` (string, optional) — The stable code on the refusals that carry it here instead of in `error`: stale_edit (409 on an expert save).
- `requestId` (string, optional) — The X-Request-Id of the call, to quote to support.
- `upgradeHint` (ErrorUpgradeHint, optional) — On 402 payment_required and 403 plan_limit: what fixes it.
- `requiredScopes` (list of string, optional) — On 403 insufficient_scope: what the route needs.
- `missingScopes` (list of string, optional)
- `retryAfterSeconds` (integer, optional) — On 429: how long to wait.
- `retryAt` (datetime, optional, nullable)
- `timeZone` (string, optional, nullable)
- `localTime` (string, optional, nullable)
- `state` (string, optional, nullable)
- `exceptionsAllowed` (boolean, optional) — On 400 outside_calling_hours: whether `callingHoursException` may be sent.

## Types

### OAuthTokenWorkspace

- `id` (string, required) — A UUID.
- `name` (string, required)

### ErrorUpgradeHint

On 402 payment_required and 403 plan_limit: what fixes it.

- `action` (enum, optional)
  - Allowed values: `top_up`, `upgrade`, `contact`
- `planCode` (string, optional) — The smallest plan that allows it, when action is upgrade.
- `href` (string, optional) — Where to go in the app.

## Examples

**Request**

```json
{
  "grant_type": "authorization_code",
  "code": "string",
  "redirect_uri": "string",
  "client_id": "string",
  "code_verifier": "string"
}
```

**Response**

```json
{
  "access_token": "string",
  "token_type": "bearer",
  "scope": "string",
  "workspace": {
    "id": "string",
    "name": "string"
  },
  "connection_id": "string",
  "webhook_id": "string",
  "webhook_secret": "string",
  "webhook_error": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.rydhm.ai/v1/oauth/token"

payload = {
    "grant_type": "authorization_code",
    "code": "string",
    "redirect_uri": "string",
    "client_id": "string",
    "code_verifier": "string"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.rydhm.ai/v1/oauth/token';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"grant_type":"authorization_code","code":"string","redirect_uri":"string","client_id":"string","code_verifier":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```