Skip to main content
Availability: This feature is live on Portkey Cloud.For self-hosted deployments
  • Airgapped: Backend v1.13.0+
  • Hybrid: Gateway Enterprise v2.5.0+.
Most older versions are compatible, but there are known edge cases around cache invalidation during the transition window. We recommend upgrading to the versions above for full support.

​
Overview

API Key Rotation enables you to replace API key secrets without causing service disruption. When a key is rotated:
  • A new secret is generated immediately.
  • The previous secret remains valid for a configurable transition period, allowing time to update existing integrations.
  • After the transition period ends, the old secret is automatically revoked.
You can initiate rotation:
  • Manually, on demand
  • Automatically, using a defined schedule
Key Characteristics
  • The API key ID remains unchanged during rotation.
  • Only the secret value is updated.
  • Existing usage data, such as budget tracking, cost attribution, and analytics - continues to be associated with the same key.

​
Key Concepts

ConceptDescription
RotationReplaces the current API key secret with a newly generated secret
Transition PeriodA configurable window during which both the previous and new secrets remain valid (minimum and default: 30 minutes)
Rotation PolicyA per-key configuration that defines when automatic rotation occurs
Key VersionA previous secret retained temporarily during the transition period

​
How Rotation Works

  1. A new API key secret is generated.
  2. The current secret is retained as a previous version, with a key_transition_expires_at timestamp.
  3. The API key is updated with the new secret, and last_rotated_at is recorded.
  4. The new secret becomes immediately valid for authentication.
  5. If a rotation_period is configured, next_rotation_at is recalculated for the next cycle.
During the transition window
  • Both the previous and current secrets are accepted.
  • Requests authenticated with either secret resolve to the same API key.

​
Transition Window Lifecycle

​
Rotation Modes

​
Manual Rotation

Triggered via API call. The caller receives the new key in the response. Endpoint: POST /v2/api-keys/:apiKeyId/rotate Request body (optional): 
{
  "key_transition_period_ms": 3600000
}
  • key_transition_period_ms — overrides the policy/default transition period for this rotation. Minimum: 1800000 (30 min).
Response: 
{
  "id": "<api-key-id>",
  "key": "<new-key-secret>",
  "key_transition_expires_at": "2026-04-08T12:30:00.000Z"
}
Constraints:
  • Cannot rotate if a previous version is still in transition. Wait for the transition to expire first.
  • If a rotation policy with rotation_period exists, the transition period must be shorter than the rotation period.
Required scope: *.rotate (e.g., organisation-service-api-keys.rotate, workspace-user-api-keys.rotate)

​
Automatic Rotation

Automatic rotation is handled by a background worker that runs on a recurring schedule. On each run, the worker executes the following phases in order:
PhaseDescription
Expire old versionsMarks key versions whose transition window has ended as EXPIRED, making them unusable
Rotate due keysRotates keys that have reached their scheduled rotation time, issuing a new secret and updating the next rotation timestamp
Transition expiry warningsSends notifications for key versions that will expire within the next 24 hours
Upcoming rotation warningsSends notifications for keys scheduled to rotate within the next 24 hours

​
Rotation Policy Configuration

A rotation policy can be attached to any API key at creation or via update.
FieldTypeRequiredDescription
rotation_period"weekly" | "monthly"One of rotation_period or next_rotation_atRecurring schedule. Weekly rotates every Monday 00:00 UTC; monthly rotates on the 1st of each month 00:00 UTC
next_rotation_atISO 8601 datetimeOne of rotation_period or next_rotation_atExplicit one-time or override date for the next rotation (normalized to UTC midnight)
key_transition_period_msinteger (ms)NoHow long the old key stays valid after rotation. Min: 1800000 (30 min). Default: 1800000
  • key_transition_period_ms must be strictly less than the rotation period duration.
  • If both rotation_period and next_rotation_at are provided, next_rotation_at takes precedence for the upcoming rotation.
  • Subsequent rotations follow the rotation_period.
Setting a policy on create: 
{
  "name": "Production Key",
  "scopes": ["completions.write"],
  "rotation_policy": {
    "rotation_period": "monthly",
    "key_transition_period_ms": 86400000
  }
}
Updating a policy: 
{
  "rotation_policy": {
    "rotation_period": "weekly"
  }
}
Removing a policy: Set rotation_policy to null in the update request.

​
Email Notifications

These notifications are triggered during automatic rotation runs.:
EmailTriggerSubject
Rotation AlertImmediately after auto-rotation”Action Required: API Key Rotated”
Transition Expiry WarningOld key version expires within 24 hours”Reminder: Old API Key Expiring Soon”
Upcoming Rotation WarningKey scheduled to auto-rotate within 24 hours”Reminder: API Key Scheduled for Rotation”
Recipients: Organisation admins and owners, the key’s owning user (for workspace-user keys), and any custom addresses in alert_emails.

​
Reading Rotation State

GET /v2/api-keys/:apiKeyId returns the rotation policy alongside the key details: 
{
  "id": "...",
  "name": "Production Key",
  "key": "...",
  "rotation_policy": {
    "rotation_period": "monthly",
    "next_rotation_at": "2026-05-01T00:00:00.000Z",
    "key_transition_period_ms": 1800000,
    "status": "ACTIVE"
  }
}

​
Permissions & Authorization

ActionRequired Scope Pattern
Configure rotation policy*.update (same as editing the API key)
Trigger manual rotation*.rotate
View rotation policy*.read (same as reading the API key)
Admins (org admin/owner, workspace admin/manager) can rotate any key within their scope. Non-admins can only rotate their own keys.

​
Constraints & Limits

  • A maximum of two active secrets can exist per API key at any time:
    • The current secret
    • One previous secret within its transition window
  • Rotation is blocked while a transition is active (i.e., until the previous secret expires)
  • key_transition_period_ms:
    • Minimum: 30 minutes (1800000 ms)
    • Must be strictly less than the configured rotation period
  • Supported rotation_period values:
    • weekly
    • monthly
  • next_rotation_at is always normalized to UTC midnight for consistency across schedules

​
Audit Logging

Every rotation (manual and automatic) produces an audit log entry containing:
FieldValue
api_key_idThe rotated key’s ID
rotation_mode"manual" or "auto"
old_key_maskedMasked version of the old key for traceability
transition_expires_atWhen the old key stops working

​
Notes

  • Automatic rotation phases are executed sequentially within a single run.
  • A single run may process multiple keys across different phases.
  • Notifications are advisory and do not affect key validity.

Rotate API Key

Create API Key

Update API Key

Retrieve API Key

API Keys (AuthN & AuthZ)

User Roles & Permissions

Last modified on April 8, 2026