Version: 1.0.0

Truesec Armor — Public API

Unauthenticated surface: self-serve signup, public status, shared proof-pack links, and credential introspection. Everything else in the Armor API requires a credential — see the partner reference.

Authentication

Headless callers authenticate with a Partner API Key bearer token (Authorization: Bearer halo_live_... / halo_test_..., minted at POST /v1/partner-keys — the token is shown exactly once). halo_test_* keys are scoped to an isolated sandbox companion tenant, never your real tenant. Browser sessions use the OIDC login flow (/v1/auth/login, session cookie). Introspect any credential at GET /v1/auth/whoami. Operations marked with an empty security list are callable anonymously.

Tenancy

Tenant-scoped operations act on the tenant in the X-Tenant-Id header. Partner API Keys are bound to exactly one tenant; session principals with access to several tenants must send the header explicitly. The server validates membership on every request — the header selects, it never grants.

Rate limits

When per-tenant rate limiting is enabled, every response carries RateLimit-Policy: "tenant";q=<limit>;w=<window-s> and RateLimit: "tenant";r=<remaining>;t=<reset-s> (draft-ietf-httpapi-ratelimit-headers). 429 responses include Retry-After.

Idempotency

Mutating requests (POST/PUT/PATCH/DELETE) may send an Idempotency-Key header (opt-in, Stripe-style): a retry with the same key within 24h replays the cached first 2xx response (Idempotency-Replayed: true) instead of executing twice; a concurrent duplicate gets 409.

Pagination

List endpoints are cursor-first and opt-in: the default response keeps each endpoint's original shape; passing cursor and/or limit switches to a {"<resource>": [...], "page": {"next_cursor", "has_more", "limit"}} envelope. Cursors are opaque — walk page.next_cursor until has_more is false. Offset pagination is deliberately not offered on high-volume resources.

Errors

Every error is RFC 9457 application/problem+json: {"type", "title", "status", "detail", "instance", "correlation_id", ...}. detail is always a plain string. Validation failures (422) additionally carry a structured errors array. Include correlation_id (also the X-Correlation-Id header) when reporting issues.

Versioning & deprecation

The REST surface is versioned by URL major (/v1); breaking changes only ever ship in a new major. Deprecated operations are marked in this document and emit RFC 9745 Deprecation (+ RFC 8594 Sunset, + a Link rel="deprecation" migration pointer) at runtime; retired endpoints return 410 Gone with a machine-readable migration body. /health*, /metrics, /auth/* and the MCP protocol endpoint (/mcp-server/v1) sit outside the REST major.

Authentication

HTTP: Bearer Auth

Headless bearer credential: a Partner API Key (halo_live_* for the caller's own tenant, halo_test_* for its isolated sandbox companion tenant — minted at POST /v1/partner-keys) or a hosted MCP client token (halo_mcp_*). Send as Authorization: Bearer <token>. Introspect what a credential resolves to at GET /v1/auth/whoami.

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer

API Key: sessionCookie

OIDC browser session — the human-console path (/v1/auth/login). Multi-tenant principals must also send X-Tenant-Id on tenant-scoped operations.

Security Scheme Type:	apiKey
Cookie parameter name:	halo_session