API Reference

Native reference for the Tricryption Key Service Gateway REST API (v8.1) — the REST front door for integrating agentic pipelines with the Tricryption Key Service (kS). For classic enterprise applications that link the native library, see the SDK Reference instead.

These pages are generated from the committed OpenAPI 3.1 spec:

• Download openapi.yaml — feed it to your own tooling.
• New to the gateway? Start with the Integrating via the API guide, which walks the full sign-in → protect → grant → revoke arc.

Endpoints

Endpoint	Auth	Purpose
POST /login	—	Sign in and issue a server-held token
POST /logout	X-Session	Sign out
POST /keys	X-Session	Generate a new key
POST /keys/export	X-Session	Export a key wrapped to the client's ephemeral public key
POST /keys/grant	X-Session	Grant a user access to a key
POST /keys/revoke	X-Session	Revoke a user's access to a key
GET /health	—	Health and TLS fingerprint

Authentication

Authentication is a token-broker model, documented as the X-Session security scheme:

• POST /login performs a real SRP login, issues a per-user Token-Encryption (TE) token, and stores it server-side. The client receives only an opaque sessionId.
• Send that id as X-Session: <sessionId> on every authenticated request. It is a handle to the server-held token — not a bearer token, and not the token itself. The TE token never leaves the gateway.
• Per request, the gateway opens a fresh validated-TLS connection, authenticates with the stored token, runs the operation, and closes the connection. No connection is held at rest.

Token expiry is a contract, not a TTL

Tokens may expire; this spec asserts no concrete TTL. The contract is: on a 401 whose body carries { "reauth": true }, re-run POST /login and retry.

Error contract

The gateway deliberately distinguishes session-expiry from access-denial — handle them differently:

Status	Condition	Body	What the client does
400	Validation: missing fields, invalid JSON, or body larger than 1 MB.	{ "error": "<detail>" }	Fix the request; do not retry unchanged.
401	Missing or unknown/expired X-Session (session layer). No reauth flag.	{ "error": "<detail>" }	Re-login to obtain a new session id, then retry.
401 (reauth)	The server-held TE token expired or is invalid (token layer).	{ "error": "session expired", "reauth": true, "detail": "<detail>" }	Re-run POST /login and retry the request.
403	Real kS RBAC/ACL denial — the caller is not authorized.	{ "error": "<op> denied or failed", "detail": "...Authorization Failed..." }	Surface the denial. Retrying will not help until access is granted.
404	No such route.	{ "error": "no route <METHOD> <path>" }	Check method and path.
500	Other kS operation error.	{ "error": "<detail>" }	Inspect detail; treat as an operation failure, not an auth problem.
502	/login failed for a non-credential reason (kS unreachable).	{ "error": "<detail>" }	Transient/infrastructure — retry with backoff.

The three failure modes are not interchangeable

• 401 { reauth: true } → token expired → re-login and retry.
• 403 → real authorization denial → surface it (retry won't help).
• 500 → operation error → inspect detail.