API Key Rotation

Availability: API key rotation is available on all plans (Free, Growth, and Enterprise) on Portkey Cloud.For self-hosted deployments:

Airgapped: Backend v1.14.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

Concept	Description
Rotation	Replaces the current API key secret with a newly generated secret
Transition Period	A configurable window during which both the previous and new secrets remain valid (minimum and default: 30 minutes)
Rotation Policy	A per-key configuration that defines when automatic rotation occurs
Key Version	A previous secret retained temporarily during the transition period

How Rotation Works

A new API key secret is generated.
The current secret is retained as a previous version, with a key_transition_expires_at timestamp.
The API key is updated with the new secret, and last_rotated_at is recorded.
The new secret becomes immediately valid for authentication.
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:

Phase	Description
Expire old versions	Marks key versions whose transition window has ended as `EXPIRED`, making them unusable
Rotate due keys	Rotates keys that have reached their scheduled rotation time, issuing a new secret and updating the next rotation timestamp
Transition expiry warnings	Sends notifications for key versions that will expire within the next 24 hours
Upcoming rotation warnings	Sends 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.

Field	Type	Required	Description
`rotation_period`	`"weekly"` \| `"monthly"`	One of `rotation_period`, `rotation_period_days`, or `next_rotation_at`	Recurring schedule. Weekly rotates every Monday 00:00 UTC; monthly rotates on the 1st of each month 00:00 UTC
`rotation_period_days`	integer (1–365)	One of `rotation_period`, `rotation_period_days`, or `next_rotation_at`	Custom rotation cadence in days. Mutually exclusive with `rotation_period`. (Backend `v1.16.0+`)
`next_rotation_at`	ISO 8601 datetime	One of `rotation_period`, `rotation_period_days`, or `next_rotation_at`	Explicit one-time or override date for the next rotation (normalized to UTC midnight)
`key_transition_period_ms`	integer (ms)	No	How 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.

Organisation-Enforced Rotation Period

Organisation owners/admins can enforce a rotation cadence on workspace-user API keys via the user_api_key_rotation_period setting (with optional per-workspace override). The setting accepts an integer between 1 and 365 (days). (Backend v1.17.0+ stores and returns days only; weekly/monthly input is normalized to 7/30.) When set, newly-created workspace-user keys without a rotation policy automatically get the enforced cadence, and any explicit rotation_period / rotation_period_days that differs from the enforced value is rejected at create/update time. next_rotation_at cannot be manually changed on API key update while enforcement is active.

Email Notifications

These notifications are triggered during automatic rotation runs.:

Email	Trigger	Subject
Rotation Alert	Immediately after auto-rotation	”Action Required: API Key Rotated”
Transition Expiry Warning	Old key version expires within 24 hours	”Reminder: Old API Key Expiring Soon”
Upcoming Rotation Warning	Key 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

Action	Required 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
rotation_period_days (Backend v1.16.0+) accepts an integer between 1 and 365. Mutually exclusive with rotation_period.
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:

Field	Value
`api_key_id`	The rotated key’s ID
`rotation_mode`	`"manual"` or `"auto"`
`old_key_masked`	Masked version of the old key for traceability
`transition_expires_at`	When the old key stops working

Introduction

Product

Self-Hosting

Support

Overview

Key Concepts

How Rotation Works

Transition Window Lifecycle

Rotation Modes

Manual Rotation

Automatic Rotation

Rotation Policy Configuration

Organisation-Enforced Rotation Period

Email Notifications

Reading Rotation State

Permissions & Authorization

Constraints & Limits

Audit Logging

Notes

Rotate API Key

Create API Key

Update API Key

Retrieve API Key

API Keys (AuthN & AuthZ)

User Roles & Permissions

​Overview

​Key Concepts

​How Rotation Works

​Transition Window Lifecycle

​Rotation Modes

​Manual Rotation

​Automatic Rotation

​Rotation Policy Configuration

​Organisation-Enforced Rotation Period

​Email Notifications

​Reading Rotation State

​Permissions & Authorization

​Constraints & Limits

​Audit Logging

​Notes

​Related

Rotate API Key

Create API Key

Update API Key

Retrieve API Key

API Keys (AuthN & AuthZ)

User Roles & Permissions

Overview

Key Concepts

How Rotation Works

Transition Window Lifecycle

Rotation Modes

Manual Rotation

Automatic Rotation

Rotation Policy Configuration

Organisation-Enforced Rotation Period

Email Notifications

Reading Rotation State

Permissions & Authorization

Constraints & Limits

Audit Logging

Notes

Related