Public API overview

Truesec HALO exposes one versioned business API surface, /api/v1 (/v1 at the application). Routes are grouped into audience tiers — public, customer, partner, and internal — and each tier gets its own generated API reference, scoped to only the operations that tier can call. This page covers the public tier: the handful of routes that need no authenticated session at all.

The full, generated reference for this tier — every operation, request/ response schema, and status code — lives under API reference in the sidebar. It is generated directly from the same committed OpenAPI document CI staleness-checks on every change, so it never drifts from what the public tier actually accepts.

What the public tier covers

The public tier is intentionally small: status-page data, the public share view for a proof pack a customer has explicitly shared, sign-up/trial verification flows, version metadata, and the authentication handshake routes a browser-based session needs before it becomes an authenticated customer session. It does not include any tenant data, any action-proposal or approval routes, or anything that reads from a connected estate — those all require an authenticated customer or partner session and appear only in the customer/partner tiers of this documentation.

Auth model

Public-tier routes are, by design, callable without any credential. Every other tier requires one of:

• A browser session cookie, established through the OIDC login flow — used by the console and by the customer-tier documentation gate.
• A bearer token, scoped to the calling principal's tenant and role, for server-to-server integration.

Every authenticated example in this documentation shows the Authorization header explicitly; a request missing it against a non-public route is rejected, not silently downgraded to anonymous access.

Errors

Every error response uses the same shape — an RFC 9457 application/problem+json body — regardless of which route or tier produced it. There is no route-specific bespoke error format to learn.

Versioning and stability

The /api/v1 surface is the one canonical externally-facing business namespace. Breaking changes to a published operation are called out explicitly in the release notes for that version; this documentation always reflects the currently deployed contract, not a future or in-progress one.

Related docs

• Truesec HALO documentation
• Who governs HALO? (trust brief)