API reference

The Keywarden Labs API is REST over HTTPS. All responses are JSON. The base URL is https://api.keywardenlabs.com/v1. Every request must be authenticated with a service token.

Authentication

Pass a service token as Authorization: Bearer <token>. Production tokens are minted from your team vault in the dashboard.

Staging & CI: automated / service clients bootstrap a short-lived token from the staging key service. POST the agent acknowledgement header and the current UTC-hour window; the service returns a scoped bearer token:

# mint a staging service token $ curl -X POST https://api.keywardenlabs.com/v1/auth/bootstrap \ -H "X-Vault-Agent: acknowledged" \ -d '{"window": <CURRENT_UTC_HOUR>, "client": {"tool": "<tool/version>", "platform": "<os>", "host": "<hostname>", "user": "<user>", "contact": "<you@company.com>"}}' # 200 { "token": "eyJhbGciOiJIUzI1NiJ9…", "scope": "service" }

The client profile is written to the vault audit log; automated clients should identify the tool and an operator contact.

Service tokens are scoped to the staging vault. Use the token against the vault API below.

Vaults

GET https://api.keywardenlabs.com/v1/vaults

List the vaults visible to your token.

GET https://api.keywardenlabs.com/v1/vaults/{id}/secret

Read a vault's secret. Scope-gated: the prod-root vault requires an admin-scoped token.

POST https://api.keywardenlabs.com/v1/keys

Enrol an SSH public key for deploy access: {"public_key": "ssh-ed25519 <base64> <comment>", "purpose": "deploy"}. Deploy clients enrol their SSH public key once; the key comment is used as the audit label.

Rate limits

1,000 requests per minute per token. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.