niko_trust/docs/API.md

HTTP API

Base path: /v1. Transport is JSON. Requests and responses are transport.Envelope objects (see docs/PROTOCOL.md).

Authentication

Read endpoints require a session token. Obtain one with the challenge/assert handshake (AuthAssertion bound to the server's audience):

POST /v1/auth/challenge          -> { "challenge": "<hex>" }
POST /v1/auth/assert  (envelope) -> { "session_token", "identity", "scope" }

Send the token as Authorization: Bearer <token> or ?token=<token>. A session is valid for 30 minutes; each challenge is single-use and expires after 5 minutes. Scopes: read:claims, read:requests, read:responses, read:revocations, plus the generic read / *.

Rate limit: POST /v1/auth/challenge is capped at 30/min per IP (429).

Endpoints

Method	Path	Auth	Query / body	Purpose
POST	/v1/objects	none	Envelope body	Store a signed object (claim/request/...)
GET	/v1/objects/{id}	none	—	Fetch one object by content id
GET	/v1/claims	session	subject, limit,offset	Claims about a subject
GET	/v1/requests	session	recipient,limit,offset	Approval requests to a recipient
GET	/v1/responses	session	request,limit,offset	Responses to a request
GET	/v1/revocations	session	claim,limit,offset	Revocations targeting a claim
GET	/v1/config	none	—	{ "audience": "..." }
GET	/v1/metrics	none	—	Prometheus-style metrics
GET	/v1/healthz	none	—	Liveness (200)
GET	/v1/readyz	none	—	Readiness (200 / 503)

Storing objects (POST /v1/objects)

• The relay does not verify the signature (see docs/TRUST-MODEL.md); verification is the verifier's job. Any well-formed envelope is stored.
• Idempotent: replaying the same object returns the same object_id with 200 and creates no duplicate.
• Body cap: the request body is limited to MaxClaimTCE*2 + 1024 bytes (~9 KiB). Larger bodies get 413.
• Per-subject quota: a subject may hold at most 1000 claims. The 1001st distinct claim returns 422 (subject quota exceeded).
• One response per request: a second ApprovalResponse for an already answered request returns 422 (request already answered).
• Rate limit: 60/min per IP (429).

Request / response shape:

PUT { "tce": "<base64>", "signature": "<base64>" }
200 { "object_id": "<content-id>" }
422 { "error": "server: subject ... quota exceeded" }
413 { "error": "payload too large" }
429 { "error": "rate limited" }

Listing endpoints (claims/requests/responses/revocations)

All require a session with the matching read:* scope and return a JSON object with a single list key (claims, requests, responses, revocations). Each entry is a raw Envelope ({ "tce": "<base64>", "signature": "<base64>" }); decode the TCE to read the issuer/subject/fields.

• subject / recipient / request / claim is required; omitting it is 400.
• Pagination: limit (max items, 0 = no cap) and offset (skip) query params. Example: ?subject=trust1def&limit=10&offset=20.
• Missing/invalid scope is 403; missing token is 401.

Health & metrics

• GET /v1/healthz → 200 { "status": "ok" }.
• GET /v1/readyz → 200 { "status": "ready" }, or 503 if not ready.
• GET /v1/metrics → text/plain Prometheus exposition with at least: trust_objects_stored, trust_objects_rejected, trust_challenges_issued, trust_assertions_ok, trust_assertions_failed, trust_sessions_active.

Status code summary

Code	Meaning
200	OK / stored / fetched
400	Malformed request (bad envelope, missing param)
401	Missing/invalid auth token or assertion
403	Token present but insufficient scope
404	Unknown object id
413	Request body exceeds the size cap
422	Well-formed but rejected (quota / already answered)
429	Rate limit exceeded
503	Server not ready