API Keys

DB-backed API keys are Ductor's durable, revocable, per-tenant credentials for service-to-service traffic. This page owns the security model: how a presented key is verified, what is stored, how roles and scopes are evaluated, and what threat boundaries the auth path enforces. Unlike JWTs (validated against your IdP) these are owned by Ductor and validated against the tenant_api_key table.

Enable the auth path first:

export DUCTOR_AUTH_API_KEY_ENABLED=true

The lifecycle API

Three REST endpoints (each also available over Connect-RPC). The tenant is always taken from the authenticated request context, never from the request body — you cannot mint or list keys for another tenant.

Mint a key

curl -sS -X POST https://api.example.com/api/v2/api-keys \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline Key",
    "roles": ["operator"],
    "scopes": ["workflow:read", "workflow_run:read"],
    "environment_mode": "non_production_only",
    "expires_at": "2026-12-31T00:00:00Z"
  }'

Response — note secret, returned here and never again:

{
  "key": {
    "id": "b1e7…-uuid",
    "name": "CI Pipeline Key",
    "key_prefix": "duk_b1e7",
    "roles": ["operator"],
    "scopes": ["workflow:read", "workflow_run:read"],
    "status": "active",
    "environment_mode": "non_production_only",
    "environment_keys": [],
    "created_at": "2026-07-11T12:00:00Z"
  },
  "secret": "duk_b1e7_live_9f2c8a7b6d5e4f3a2b1c0d9e8f7a6b5c"
}

Use the returned secret on subsequent calls:

curl -sS https://api.example.com/api/v2/workflow-runs \
  -H "X-API-Key: duk_b1e7_live_9f2c8a7b6d5e4f3a2b1c0d9e8f7a6b5c"

List keys

Returns every key for the tenant — active and revoked, newest first — so a management UI can show full history. Records never include the secret or its hash.

curl -sS https://api.example.com/api/v2/api-keys \
  -H "Authorization: Bearer $ADMIN_JWT"

{
  "keys": [
    {
      "id": "b1e7…-uuid",
      "name": "CI Pipeline Key",
      "key_prefix": "duk_b1e7",
      "roles": ["operator"],
      "status": "active",
      "created_at": "2026-07-11T12:00:00Z",
      "last_used_at": "2026-07-11T12:03:41Z"
    }
  ],
  "total_count": 1
}

Revoke a key

curl -sS -X POST https://api.example.com/api/v2/api-keys/b1e7…-uuid/revoke \
  -H "Authorization: Bearer $ADMIN_JWT"

Revocation takes effect immediately — the auth path only ever considers active keys. Revoking an already-revoked key is a no-op. The action cannot be undone.

What a key carries

Roles

The optional roles list is validated against the RBAC role catalog: the built-in viewer, operator, admin, and service, plus any module-registered roles. An unknown role name is a 400. At auth time the role bundle expands to its scopes. See Authorization for what each role grants.

Scopes

The optional scopes list attaches per-key resource:action scopes. Each must be a known scope in the catalog (an unknown scope is rejected at mint time). Per-key scopes are unioned with the role-bundle expansion when the authorizer evaluates a request — so you can grant a key exactly workflow:read without handing it a whole role.

Environment scope

environment_mode constrains where a key may mutate environment-owned artifacts:

environment_keys is only valid with selected (and must be non-empty there); supplying keys without selected — or with any other mode — is rejected. If you pass environment_keys but omit environment_mode, the server treats the request as selected. Read-only calls are still governed by RBAC scopes regardless of environment mode.

Expiry

expires_at is an optional RFC-3339 timestamp. Unset means the key never expires. The authentication path rejects a key presented after its expiry.

Storage & validation model

• Never plaintext. Only two things are persisted: the key prefix (first 8 characters, e.g. duk_b1e7, shown for identification) and a bcrypt hash of the full key. The scheme the mint side writes is exactly what the auth side validates against.
• Prefix-narrowed lookup. On a presented key, the store fetches active candidates by prefix — at most one or two rows — and bcrypt-compares against those. This keeps validation cheap and bounds the work an attacker can force.
• Role storage. The per-key role bundle was added in migration 142; an empty role list simply disables the role gate while per-key scopes still apply.

Rotation

Keys have no in-place rotation — rotation is mint-then-revoke, which lets you cut over with zero downtime:

Auditing key lifecycle

Because API keys are bearer credentials, their issuance, status changes, and revocation are recorded to the same audit stream the authorizer uses (tenant.apikey.created, tenant.apikey.status_changed, tenant.apikey.revoked). The audit event carries the actor, tenant, and key ID — never the plaintext or the key name. Configure the audit sink as described in Authorization → Audit logging.