API Keys And Agents
API key lifecycle, proof scopes, agent enrollment, and automation boundaries.
API Keys And Agents
API keys are organization-scoped automation credentials. They are managed by
CLIENT_ADMIN today, not by PLATFORM_ADMIN admin routes.
API Key Routes
| Action | Route | Role |
|---|---|---|
| List keys | GET /api/v1/api-keys | CLIENT_ADMIN |
| Create key | POST /api/v1/api-keys | CLIENT_ADMIN |
| Rotate key | POST /api/v1/api-keys/{id}/rotate | CLIENT_ADMIN |
| Revoke key | POST /api/v1/api-keys/{id}/revoke or DELETE /api/v1/api-keys/{id} | CLIENT_ADMIN |
Create request:
{
"name": "CI proof uploader",
"organization_id": "22222222-2222-4222-8222-222222222222",
"scopes": ["proofs:write", "proofs:read"]
}
The generated secret is returned once. Store it immediately. Later list calls show metadata and prefix only.
Scopes
| Scope | Allows |
|---|---|
proofs:write | Submit proofs through /api/v1/proofs, /api/v1/proofs/bulk, or /ingest/v1/proofs when other route checks pass. |
proofs:read | Read proof detail and proof status where scope-based access is accepted. |
API keys do not grant user management, billing, license allocation, certificate revocation, or admin access.
Agent Enrollment
| Action | Route | Auth |
|---|---|---|
| Enroll agent | POST /ingest/v1/enroll | One-time enrollment code |
| Submit agent proof | POST /ingest/v1/proofs | Enrolled-agent API key with proofs:write |
Enrollment codes are one-time ISO tokens. The backend stores only token prefix
and hash, accepts only pending and unexpired tokens, and marks the enrollment
consumed when it returns the generated agent API key. The generated key is
write-only with proofs:write; use regular API key creation when automation
also needs readback.
Enrollment can record agent_name, agent_version, forwarded mTLS certificate
subject/fingerprint headers, and agent-reported identity headers. These fields
are trust metadata until the final Exaion agent PKI roots and verification
policy are configured.
The local dev stack seeds an optional enrollment code when
DATABASE_SEED_DEV=true and AGENT_DEV_ENROLLMENT_ENABLED=true:
wipe_dev_enroll.0123456789abcdef0123456789abcdef
The seeded dev proof automation key is:
wipe_dev_agent.0123456789abcdef0123456789abcdef
Use seeded credentials only for local smoke tests.
Rotation And Revocation
Rotation replaces the secret and returns the new secret once. Revocation sets
revoked_at and also revokes linked agent enrollment state when the key is tied
to an agent enrollment. Linked enrolled-agent authentication updates
last_seen; enrollment itself records consumed_at instead.
When MFA recency is enabled, create, rotate, and revoke require recent MFA.
Platform Admin Checklist
| Check | Why |
|---|---|
| Confirm key owner organization. | API keys are tenant and organization scoped. |
| Confirm scopes are minimal. | Enrolled-agent keys are proofs:write only; use separate automation keys for readback. |
| Confirm audit entries. | Create, rotate, and revoke actions write audit records. |
| Confirm revoked keys fail. | A revoked key must not submit proofs or enroll agents. |
Open Platform Gap
The cahier expects a fuller platform-admin view of automation and agent
credential lifecycle. Current backend enforcement keeps API key lifecycle inside
CLIENT_ADMIN routes. Add admin read-only or break-glass routes only after the
product policy for platform access to tenant automation secrets is explicit.