Aletheia documentation
Overview
The HTTP API behind the Aletheia infrastructure control plane.
Aletheia API 1
Section titled “Aletheia API 1”Aletheia connects live AWS resources, infrastructure-as-code, ownership, and change history into one model of what you actually run. This API is the same one the product’s own interface uses.
Base URL and versioning
All business endpoints live under /api/v1. The version is in the path, so a
future v2 can ship without breaking existing clients.
Authentication
Three schemes, each for a different kind of caller:
bearerAuth— CLIs, scripts, and server-to-server callers. Obtain an access token fromPOST /api/v1/auth/login. Exempt from CSRF.sessionCookie+csrfToken— browsers. The API sets HttpOnlycritias_at/critias_rtcookies at login; mutating requests must also echo thecritias_csrfcookie in anX-CSRF-Tokenheader.ingestToken— CI pipelines, on/ingest/*only. Cannot read data.
Errors
Every error returns a flat {code, message} object. Branch on code: it is
a stable contract, while message is human-readable text that may be
reworded.
Tenancy
All data belongs to exactly one organization, and no query crosses that
boundary. A resource belonging to another organization returns 404, not
403, so that callers cannot probe for its existence.
Authentication
Section titled “Authentication”bearerAuth
Section titled “bearerAuth”For programmatic clients. Authorization: Bearer <access token>, obtained
from POST /api/v1/auth/login. Bearer-authenticated requests are exempt
from CSRF, because a header set deliberately by your code cannot be
forged by a third-party site the way an automatically-attached cookie can.
Security scheme type: http
Bearer format: JWT
sessionCookie
Section titled “sessionCookie”For browsers. The API sets HttpOnly, SameSite=Strict critias_at and
critias_rt cookies at login. Mutating requests must additionally send
the csrfToken header.
Security scheme type: apiKey
Cookie parameter name: critias_at
csrfToken
Section titled “csrfToken”Double-submit CSRF token. Read the value of the (deliberately non-HttpOnly)
critias_csrf cookie and echo it in this header on every mutating,
cookie-authenticated request. Compared in constant time. Safe methods are
exempt.
Security scheme type: apiKey
Header parameter name: X-CSRF-Token
ingestToken
Section titled “ingestToken”Org-scoped CI ingest token, valid ONLY on /api/v1/ingest/*. Despite the
identical header shape this is not a user token: it cannot read the
inventory or reach any other endpoint. Create one under
Administration -> Ingest tokens; the raw value is shown once.
Security scheme type: http