---
title: "Exchange a 1claw token for an OIDC federation token (RFC 8693)"
method: POST
path: "/v1/auth/federated-token"
tags: ["Authentication"]
---

# Exchange a 1claw token for an OIDC federation token (RFC 8693)

`POST /v1/auth/federated-token`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/auth/federated-token`
- Auth: none required

Mints a short-lived RS256-signed JWT targeted at an external
relying party (e.g. Anthropic Workload Identity Federation).
The relying party validates the token via this issuer's JWKS
URL (`/.well-known/jwks.json`) and exchanges it for its own
short-lived service credentials.

Requirements:
- The agent that owns the `subject_token` must have
  `federation_enabled = true` and the requested `audience`
  must appear in `federation_audiences`.
- The `subject_token` must be a valid 1claw agent JWT or
  `ocv_` API key.
- Optional `scope` narrows the agent's existing scopes — it
  cannot escalate.

Returns 503 when `ONECLAW_JWT_RS256_SIGNING_KEY_ID` is not
configured on the server.

## Request body

- TokenExchangeRequest: RFC 8693 token-exchange request body. `subject_token_type` accepts the standard JWT URI or 1claw's API-key URI: - `urn:ietf:params:oauth:token-type:jwt` - `urn:1claw:params:oauth:token-type:api-key`
  - `grant_type` 'urn:ietf:params:oauth:grant-type:token-exchange', required
  - `subject_token` string, required: 1claw JWT or `ocv_` API key authorising the exchange.
  - `subject_token_type` 'urn:ietf:params:oauth:token-type:jwt' | 'urn:1claw:params:oauth:token-type:api-key', required
  - `audience` string, uri, required: Required `aud` claim for the issued federation token (must be in agent's allowlist).
  - `scope` string: Optional space-separated subset of the agent's existing scopes.
  - `requested_token_type` string: Optional. Defaults to `urn:ietf:params:oauth:token-type:jwt`.

## Response `200`

Federation token issued

- TokenExchangeResponse
  - `access_token` string, required: RS256-signed federation JWT.
  - `issued_token_type` string, required
  - `token_type` string, required
  - `expires_in` integer, required
  - `scope` string

## Other responses

- `400`: Invalid request
- `401`: Authentication required or invalid
- `403`: Insufficient permissions
- `503`: RS256 signing key not configured

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/ae109b496830?raw)