Key Rotation

Production - ApiKeyRotationService - 4 rotation endpoints

Key rotation allows seamless replacement of API keys with zero downtime. During the grace period, both the old and new keys are valid.

6.6.3Rotation Flow

Old Key (active) --> Rotate --> Grace Period (both valid) --> Old Key Revoked
                                    |
                                    +--> New Key (active)

Initiate Rotation

curl -X POST http://localhost:8081/api/v1/api-keys/15/rotate \
  -H "Authorization: Bearer <access-token>"

Response (200 OK)

{
  "newKeyId": 16,
  "newFullKey": "mk_live_x9y8w7v6u5t4s3r2q1p0...",
  "oldKeyId": 15,
  "gracePeriodEnds": "2026-02-19T10:00:00Z",
  "status": "ROTATING"
}

Check Rotation Status

curl -X GET http://localhost:8081/api/v1/api-keys/15/rotation-status \
  -H "Authorization: Bearer <access-token>"

Complete Rotation Immediately

curl -X POST http://localhost:8081/api/v1/api-keys/15/rotation/complete \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Migration complete" }'

Cancel Rotation

curl -X POST http://localhost:8081/api/v1/api-keys/15/rotation/cancel \
  -H "Authorization: Bearer <access-token>"

Rotation Recommendations

Get keys that should be rotated:

curl -X GET http://localhost:8081/api/v1/api-keys/rotation-recommendations \
  -H "Authorization: Bearer <access-token>"

Error Codes

Code	HTTP Status	Description
`ROTATION_IN_PROGRESS`	409	Rotation already in progress
`NO_ROTATION_IN_PROGRESS`	404	No rotation to cancel or complete
`UNAUTHORIZED_ROTATION`	403	User does not own this key

Creating Keys Scopes & Limits