---
title: "Exchange Token"
method: POST
path: "/api/v1/oauth/token"
tags: ["oauth"]
---

# Exchange Token

`POST /api/v1/oauth/token`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `Otari-Key`
  - API key in header `x-api-key`

Exchange an identity token for an access token (the RFC 7523 ``jwt-bearer`` grant).

The identity token must verify against an issuer on ``federation_issuers`` and match the federation rule
``federation_rule_id`` names. ``organization_id``, ``workspace_id`` and ``service_account_id``, where set, must
be the UUIDs of the rule's key's organization and workspace and the key's id. The access token authenticates as
that key until ``expires_in`` runs out, the rule is deleted or the key stops passing its checks.

Every refusal of the identity token answers 401 ``invalid_grant`` with the same description.

## Request body

- FederationTokenRequest: An RFC 7523 ``jwt-bearer`` token request, as the Anthropic SDKs and Claude Code send it. Every field is optional here so that a missing one is answered in the RFC 6749 error shape rather than as a validation error. Fields the request does not use are ignored.
  - `assertion` string, nullable: The identity token.
  - `federation_rule_id` string, nullable: The id of the federation rule the identity token must match.
  - `grant_type` string, nullable: urn:ietf:params:oauth:grant-type:jwt-bearer
  - `organization_id` string, nullable: When set, the UUID of the organization of the rule's key.
  - `service_account_id` string, nullable: When set, the id of the rule's key.
  - `workspace_id` string, nullable: When set, the UUID of the rule's key's workspace.

## Response `200`

Successful Response

- FederationTokenResponse: An access token, as RFC 6749 section 5.1 shapes it. Present it as a bearer token in place of the key.
  - `access_token` string, required
  - `expires_in` integer, required: Seconds until the access token expires.
  - `token_type` string

## Other responses

- `400`: invalid_request or unsupported_grant_type
- `401`: invalid_grant
- `422`: Validation Error
- `503`: temporarily_unavailable

## Changes

- **2026-10-17** `63724f6891aa`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mozilla-ai/apis/otari/changes/api/v1/oauth/token/post.md)

---

[API](https://skmtc.dev/mozilla-ai/apis/otari.md) · [All operations](https://skmtc.dev/mozilla-ai/apis/otari/llms.txt) · [OpenAPI document](https://skmtc.dev/mozilla-ai/apis/otari/revisions/c221df17a307?raw)