Use STS Endpoint

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 to understand how Gateway validates inbound authority and exchanges with STS per request.

Related Pages

• Exchange Tokens
• OAuth Package
• Mandates