---
title: "Exchange Tokens"
url: "https://docs.caracal.run/architecture/token-exchange-flow/"
markdown_url: "https://docs.caracal.run/markdown/architecture/token-exchange-flow.md"
description: "How STS exchanges authority for scoped Caracal mandates."
page_type: "architecture"
concepts: []
requires: []
---

# Exchange Tokens

Canonical URL: https://docs.caracal.run/architecture/token-exchange-flow/
Markdown URL: https://docs.caracal.run/markdown/architecture/token-exchange-flow.md
Description: How STS exchanges authority for scoped Caracal mandates.
Page type: architecture
Concepts: none
Requires: none

---

STS implements the token exchange boundary. Workloads, SDKs, `caracal run`, and Gateway submit existing authority plus requested resources and receive scoped mandates.

## Exchange Sequence

```mermaid
sequenceDiagram
  participant Client as SDK/caracal run/Gateway
  participant STS
  participant PG as Postgres
  participant Redis
  participant Audit
  Client->>STS: POST /oauth/2/token
  STS->>PG: authenticate app, load grants/resources/policies/sessions
  STS->>Redis: observe invalidation and revocation state
  STS->>STS: evaluate policy and constraints
  alt step-up required
    STS-->>Client: interaction_required with challenge id
  else allowed
    STS-->>Client: mandate JWT
    STS->>Redis: signed audit event
    Redis->>Audit: audit-ingestor consumes
  end
```

## Inputs

| Input | Purpose |
| --- | --- |
| `grant_type` | OAuth token-exchange request type. |
| `subject_token` | Existing user, service, application, or agent authority. |
| `actor_token` | Optional actor authority for delegated exchange. |
| `resource` | Target resource identifiers. |
| `scope` | Requested resource scopes. |
| `zone_id` | Tenant boundary. |
| `application_id` and client credential | Authenticates the calling application. |
| `session_id`, `agent_session_id`, `delegation_edge_id` | Authority anchors for session/delegation checks. |
| `challenge_id` / `challenge_response` | Step-up completion. |

## TTL Contracts

| Mandate type | Contract |
| --- | --- |
| Resource mandate | Capped at 15 minutes. |
| Session mandate | Capped at 60 minutes. |
| Runtime-injected credential | `caracal run` injects credentials capped at 15 minutes after STS exchange. |

Gateway performs a per-request exchange and rejects inbound tokens that are too close to expiry before proxying.

## Gateway-Authenticated Exchange

Gateway exchanges with STS using a request signature, timestamp, and nonce over the token exchange request. STS verifies the Gateway HMAC key and consumes the nonce before trusting the Gateway-authenticated path.

## Next Step

Use [Coordinate Agents](/architecture/delegation-flow/) to see how agent sessions and delegation edges feed token exchange.

## Related Pages

- [Issue Mandates](/services/sts/)
- [Mandates](/concepts/mandate/)
- [Step-Up Challenges](/concepts/step-up/)
- [Use STS Endpoint](/api/sts/)