Key Rotation

Online key rotation without downtime. Re-encrypts secrets, signing keys, and the mTLS CA private key. Requires step-up auth.

Authentication

Authorization: Bearer <elevated_token> (step-up required for write operations).

Endpoints

POST /api/operator/keys/rotate

Initiate rotation. Scope: secrets, signing-keys, mtls-ca, all.

Input: ~~~json { "scope": "all" } ~~~

Output: ~~~json { "job_id": "rot-uuid", "scope": "all", "status": "in_progress", "estimated_duration_seconds": 30 } ~~~

GET /api/operator/keys/rotation-status

Poll rotation progress. Response includes status, progress_pct, started_at, completed_at.

GET /api/operator/keys/history

List past rotation events with triggered_by field.

POST /api/operator/keys/re-encrypt-all

Standalone re-encryption sweep after manually rotating BUTTRBASE_SECRETS_KEY. Idempotent.

KMS Integration

If BUTTRBASE_KMS_PROVIDER=external: AWS KMS (BUTTRBASE_KMS_AWS_KEY_ARN), GCP KMS (BUTTRBASE_KMS_GCP_KEY_NAME), or Vault Transit (BUTTRBASE_KMS_VAULT_KEY_NAME).

Error Reference

| Status | Code | Meaning | |---|---|---| | 403 | step_up_required | Elevated token required | | 409 | rotation_in_progress | Another rotation already running | | 422 | unknown_scope | Invalid scope value | | 503 | kms_unavailable | External KMS unreachable |