---
title: "Use STS Endpoint"
url: "https://docs.caracal.run/api/sts/"
markdown_url: "https://docs.caracal.run/markdown/api/sts.md"
description: "OAuth token exchange, JWKS, step-up, and internal policy endpoints served by STS."
page_type: "api"
concepts: []
requires: []
---

# Use STS Endpoint

Canonical URL: https://docs.caracal.run/api/sts/
Markdown URL: https://docs.caracal.run/markdown/api/sts.md
Description: OAuth token exchange, JWKS, step-up, and internal policy endpoints served by STS.
Page type: api
Concepts: none
Requires: none

---

STS is served on port `8080` and issues scoped Caracal mandate JWTs.

## Public Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/oauth/2/token` | OAuth token exchange for resource, session, Gateway, or delegated mandates. |
| `GET` | `/.well-known/jwks.json?zone_id={zone}` | Public signing keys for mandate verification, scoped per zone. |
| `GET` | `/step-up/{id}` | Step-up challenge status. |
| `GET` | `/health` | Liveness check. |
| `GET` | `/ready` | Readiness check. |
| `GET` | `/metrics` | Prometheus metrics. |
| `GET` | `/metrics.json` | JSON metrics. |

## Token Exchange Request

`POST /oauth/2/token` accepts form-encoded parameters.

| Parameter | Purpose |
| --- | --- |
| `grant_type` | OAuth grant type. |
| `subject_token`, `subject_token_type` | Existing authority to exchange. |
| `actor_token` | Optional actor authority. |
| `resource` | One or more target resource identifiers. |
| `scope` | Requested scopes. |
| `zone_id` | Zone boundary. |
| `application_id` | Calling application. |
| `client_secret`, `client_assertion`, `client_assertion_type` | Application authentication. |
| `session_id`, `agent_session_id`, `delegation_edge_id` | Session and delegation anchors. |
| `ttl_seconds` | Requested TTL. |
| `challenge_id`, `challenge_response` | Step-up completion. |

## Responses

Successful exchanges return an OAuth-style token response with `access_token`, `token_type`, `expires_in`, and related fields. Step-up returns `interaction_required` with challenge data. Errors use the shared `error` and `error_description` shape.

## Internal Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/internal/policy/simulate` | Simulate policy input. |
| `GET` | `/internal/policy/status/{zoneID}` | Inspect policy load status. |
| `POST` | `/internal/zones/{zoneID}/signing-key/rotate` | Rotate zone signing key. |

Internal endpoints are for service/admin integration, not normal application traffic.

## Next Step

Use [Proxy Through Gateway](/api/gateway/) to understand how Gateway validates inbound authority and exchanges with STS per request.

## Related Pages

- [Exchange Tokens](/architecture/token-exchange-flow/)
- [OAuth Package](/sdks/oauth/)
- [Mandates](/concepts/mandate/)