Selected control-API endpoints

The dashboard, the CLI, and any external automation all speak the same JSON HTTP API. This page lists the endpoints used in the workflow walkthroughs in this section. The full surface is larger — consult the OpenAPI document for the rest.

Info

All non-GET calls require Content-Type: application/json and, when RBAC is enabled, Authorization: Bearer <token>.

Health

Method · Path	RBAC	Notes
GET /healthz	none	Kubernetes liveness
GET /readyz	none	Kubernetes readiness
GET /metrics	none	Prometheus exposition
GET /api/health	viewer	Detailed component health JSON
GET /ca.crt	none	The proxy's CA cert in PEM

Mode

Method · Path	RBAC	Notes
GET /api/mode	viewer	Current operating mode
POST /api/mode	admin	{"mode":"discovery|shadow|enforcement"}

Placeholders & escrow

Method · Path	RBAC	Notes
GET /api/placeholders	operator	List vault entries
POST /api/placeholders	operator	Upsert — same name, new value rotates
GET /api/escrow	operator	Inventory of escrowed credentials
GET /api/surrogates	operator	Currently active surrogates
GET /api/surrogates/{id}	operator	Surrogate detail
GET /api/surrogates/timeline	operator	Recent surrogate-lifecycle events
POST /api/surrogates/revoke	admin	{"surrogate":"xcbr_…"}

Onboarding (adopt-from-traffic)

Method · Path	RBAC	Notes
GET /api/onboarding/summary	viewer	Counts / KPI
GET /api/onboarding/candidates	operator	Unmanaged-credential candidates
POST /api/onboarding/candidates/{escrow_id}/adopt	operator	{"placeholder":"XCALIBUR_…"}

Identity

Method · Path	RBAC	Notes
GET /api/sessions	operator	Active sessions
POST /api/sessions/{id}/revoke	admin	Cascade-revoke all surrogates from this session
GET /api/proxy-identities	operator	Live session-bound bearers
POST /api/proxy-identities/revoke	admin	{"id":"…"}
GET /api/service-credentials	operator	Long-lived bearers
POST /api/service-credentials	admin	{"name":…,"user":…,"source_network":…,"allowed_domains":[…]}
DELETE /api/service-credentials/{id}	admin	Revoke and delete

Fleet & namespaces

Method · Path	RBAC	Notes
GET /api/fleet/workloads	operator	Workloads + attestation type
POST /api/fleet/enroll	admin	Enroll a workload (or token-exchange path)
GET /api/fleet/namespaces	operator	Hierarchical namespaces
POST /api/fleet/namespaces	admin	Create / update — ?force=true overrides cascade
GET /api/fleet/health	viewer	Aggregated health
GET /api/fleet/rate-limiter	viewer	Per-principal rate-limiter state

Egress policy

Method · Path	RBAC	Notes
GET /api/policy/egress	operator	Allow + block lists
POST /api/policy/egress/allow	operator	{"domain":…,"reason":…,"require_auth":bool}
POST /api/policy/egress/block	operator	{"domain":…,"reason":…}
DELETE /api/policy/egress/allow?domain=…	operator	Remove allow
DELETE /api/policy/egress/block?domain=…	operator	Remove block

Translation authorisation

Method · Path	RBAC	Notes
GET /api/policy/translation	operator	List rules
POST /api/policy/translation	admin	Create / update
DELETE /api/policy/translation/{id}	admin	Delete
POST /api/policy/translation/dry-run	operator	Match candidate request without recording
POST /api/policy/translation/evaluate	operator	Match and record (audit row written)

Cryptographic mediation

Method · Path	RBAC	Notes
GET /api/crypto/jwt-bearer/mappings	operator	List
POST /api/crypto/jwt-bearer/mappings	admin	Create
GET /api/crypto/dpop/mappings	operator	List
POST /api/crypto/dpop/mappings	admin	Create
GET /api/crypto/mtls/mappings	operator	List
POST /api/crypto/mtls/mappings	admin	Create — returns surrogate authority
GET /api/crypto/sigv4/mappings	operator	List
POST /api/crypto/sigv4/mappings	admin	Create

Audit & forensics

Method · Path	RBAC	Notes
GET /api/audit/search?limit=…&q=…&type=…	operator	Free-form audit search
GET /api/ssh-recordings	operator	SSH session recordings inventory
GET /api/incidents/{sessionId}/export	operator	Forensic bundle: events + lineage + surrogates

Discovery & threat

Method · Path	RBAC	Notes
GET /api/flows	operator	Live flow inventory
GET /api/domains	operator	Domain-classification cache
GET /api/workstation/summary	viewer	KPI
GET /api/workstation/first-seen	operator	First-seen destinations
GET /api/workstation/suspicious	operator	Suspicious-activity rows + reasons
GET /api/threat-intel/stats	viewer	Threat-intel hit counts
GET /api/traffic-id/stats	viewer	Adapter coverage / classification rate
GET /api/ct-monitor/status	viewer	Certificate Transparency monitor

Operations & runtime

Method · Path	RBAC	Notes
GET /api/config/surrogate-ttl	operator	Current surrogate TTL
PUT /api/config/surrogate-ttl	admin	{"surrogate_ttl":"24h"}
POST /api/config/reload	admin	Hot reload reloadable config keys
GET /api/key-rotation	viewer	Key-rotation state
POST /api/key-rotation/rotate	admin	Re-encrypt with a new DEK
GET /api/rbac/tokens	admin	RBAC token inventory

Webhooks

Method · Path	RBAC	Notes
POST /api/webhooks	admin	Register a webhook receiver
GET /api/webhooks/deliveries	operator	Delivery history

Supported webhook event types include credential_escrowed, surrogate_revoked, enforcement_block, credential_expired, suspicious_activity, circuit_breaker_open. Webhook signing secrets are encrypted at rest.

Aggregated dashboard state

Method · Path	RBAC	Notes
GET /api/dashboard/state	viewer	Aggregates many GET endpoints into a single response

This is what the dashboard polls. It dispatches to a vetted list of viewer-readable endpoints; sensitive surfaces are not exposed through it.

Token exchange (RFC 8693)

Method · Path	RBAC	Notes
POST /api/oauth/token	none	Trade a platform-issued JWT for a short-lived proxy bearer

Form-encoded body, RFC 8693 fields:

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<platform JWT>
subject_token_type=urn:ietf:params:oauth:token-type:jwt
audience=https://excalibur.…
scope=provider:github provider:stripe

See Onboarding a workload — Kubernetes.