API Keys

API keys are project-scoped secrets. The secret is shown once at creation. Prefix is always eridian_sk_. Treat keys like production database credentials: store them in your secret manager, never in source control.

Create

POST /v1/keys
Authorization: Bearer eridian_sk_...
Content-Type: application/json

{
  "project_id": "prj_legal_001",
  "name": "production-inference",
  "scopes": ["inference:write", "models:read"],
  "budget_usd": 10000,
  "expires_at": 1735689600
}

{
  "id": "key_8f3a2b1c",
  "object": "eridian.api_key",
  "prefix": "eridian_sk_",
  "secret": "eridian_sk_live_8f3a2b1c9d4e...",
  "scopes": ["inference:write", "models:read"],
  "project_id": "prj_legal_001",
  "created_at": 1718400000
}

secret is returned only on create. Subsequent GET responses redact it to eridian_sk_... plus the last four characters.

Required scope: keys:manage

List and Retrieve

GET /v1/keys?project_id=prj_legal_001
GET /v1/keys/key_8f3a2b1c

List is cursor-paginated. Responses never include the full secret.

Rotate

POST /v1/keys/key_8f3a2b1c/rotate
Authorization: Bearer eridian_sk_...

{
  "overlap_hours": 24
}

The new secret is returned once. The previous secret remains valid until overlap_hours elapses, then Eridian revokes it automatically. Rotation emits key.rotate on the audit log.

Recommended sequence:

1. Create or rotate a key with the same scopes.
2. Deploy the new secret to all replicas.
3. Confirm X-Eridian-Key-Id on canary traffic.
4. Revoke the old key if you did not use overlap.

Revoke

POST /v1/keys/key_8f3a2b1c/revoke
Authorization: Bearer eridian_sk_...

Revoked keys return HTTP 401 invalid_api_key immediately. In-flight requests that already passed the gateway complete.

Request Identity Headers

Every authenticated response includes:

Scopes

Error Codes

See Authentication for Bearer mechanics and Rate Limits for per-key ceilings.