API reference
Base URL: http://<host>:4000/api/v1
Authentication
Section titled “Authentication”Every endpoint except /health and /auth/setup requires an Authorization
header. Two token types are accepted:
| Type | Header | Use |
|---|---|---|
| API token | Authorization: Token <api-token> |
Ongoing service-to-service access |
| JWT | Authorization: Bearer <jwt> |
Short‑lived, returned by setup/login |
Error responses
Section titled “Error responses”Errors return a JSON body with a machine‑readable error and human message, e.g.:
{ "error": "forbidden", "message": "Grant does not permit this action" }Common statuses: 400 invalid input, 401 missing/invalid auth, 403 denied by
policy, 404 not found, 409 conflict (e.g. setup already completed), 429 rate
limited.
Endpoints
Section titled “Endpoints”| Resource | Endpoints |
|---|---|
| Health | GET /health |
| Auth | POST /auth/setup · POST /auth/login · GET /auth/me · POST /auth/tokens |
| Vaults | GET /vaults · POST /vaults · POST /vaults/:id/rekey |
| Secrets | GET /secrets · POST /secrets · GET /secrets/:id · GET /secrets/:id/value · PUT /secrets/:id · DELETE /secrets/:id |
| Context tokens | GET /tokens · POST /tokens · GET /tokens/:token/resolve · DELETE /tokens/:token |
| Principals | GET /principals · POST /principals · DELETE /principals/:id |
| Policies | GET /policies · GET /policies/:id · POST /policies · PUT /policies/:id · DELETE /policies/:id |
| Grants | GET /grants · POST /grants · DELETE /grants/:id |
| Access requests | POST /requests · GET /requests · PUT /requests/:id |
| Audit | GET /audit |
Selected endpoints
Section titled “Selected endpoints”GET /health
Section titled “GET /health”Unauthenticated. Returns service status and deployment mode.
{ "status": "ok", "deploymentMode": "device", "timestamp": "2026-01-01T00:00:00Z" }POST /auth/setup
Section titled “POST /auth/setup”Unauthenticated, runs once. Creates the tenant, admin principal, and default vault;
returns a JWT plus the created objects. Subsequent calls return 409.
POST /auth/tokens
Section titled “POST /auth/tokens”Issues a scoped API token. Provide a name and scopes array, e.g.
["secrets:read","secrets:write","tokens:read","tokens:write"].
GET /secrets/:id/value
Section titled “GET /secrets/:id/value”Returns the decrypted value of a secret. Always audited, including denied attempts. Subject to the requesting principal’s grants and policies.
POST /tokens · GET /tokens/:token/resolve
Section titled “POST /tokens · GET /tokens/:token/resolve”Tokenize content into an opaque token, and resolve a token back to its content. Resolution is audited and gated by the token’s grant.