Skip to content

Exchange Tokens

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

Exchange Sequence

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 to see how agent sessions and delegation edges feed token exchange.