Skip to main content
POST
/
v1
/
keys
/
rotate
Rotate API key
curl --request POST \
  --url http://localhost:8000/v1/keys/rotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "environment": "live"
}
'
{
  "new_key": {
    "key_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "api_key": "<string>",
    "environment": "<string>",
    "created_at": "2023-11-07T05:31:56Z"
  },
  "deprecated_key": {
    "key_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "key_prefix": "<string>",
    "key_suffix": "<string>",
    "environment": "<string>",
    "is_active": true,
    "status": "active",
    "created_at": "2023-11-07T05:31:56Z",
    "last_used_at": "2023-11-07T05:31:56Z",
    "deprecated_at": "2023-11-07T05:31:56Z",
    "grace_period_ends_at": "2023-11-07T05:31:56Z",
    "grace_period_days_remaining": 123
  }
}

Authorizations

​
Authorization
string
header
required

API Key authentication. Format: dk_test_ or dk_live_

Body

application/json

Request schema for creating a new API key (POST /v1/keys).

Attributes: name: Human-readable name for the API key (e.g., "Production API Key") environment: Key environment - "live" for production, "test" for testing (default: "live")

​
name
string
required

Human-readable name for this API key

Required string length: 1 - 255
​
environment
enum<string>
default:live

Key environment: 'live' for production, 'test' for testing

Available options:
live,
test

Response

New API key created and old key deprecated

Response for API key rotation (POST /v1/keys/rotate).

Returns the new key and information about the deprecated old key. The old key remains active for 7 days (grace period) to allow migration.

WARNING: The api_key field in new_key is shown only in this response. Store it securely immediately - it cannot be retrieved again.

​
new_key
CreateAPIKeyResponse · object
required

The newly created API key (includes plaintext key, shown only once)

Example:
{
  "api_key": "dk_live_abcdefghijklmnopqrstuvwxyz1234567890ABC",
  "created_at": "2024-01-15T10:30:00Z",
  "environment": "live",
  "key_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API Key"
}
​
deprecated_key
APIKeyResponse · object
required

The old key that was deprecated (with grace period information)

Examples:
{
  "created_at": "2024-01-15T10:30:00Z",
  "environment": "live",
  "is_active": true,
  "key_id": "550e8400-e29b-41d4-a716-446655440000",
  "key_prefix": "dk_live_",
  "key_suffix": "xY9z",
  "last_used_at": "2024-01-15T12:45:00Z",
  "name": "Production API Key",
  "status": "active"
}
{
  "created_at": "2024-01-01T10:30:00Z",
  "deprecated_at": "2024-01-15T10:30:00Z",
  "environment": "live",
  "grace_period_days_remaining": 5,
  "grace_period_ends_at": "2024-01-22T10:30:00Z",
  "is_active": true,
  "key_id": "660e8400-e29b-41d4-a716-446655440001",
  "key_prefix": "dk_live_",
  "key_suffix": "aBc1",
  "last_used_at": "2024-01-15T12:45:00Z",
  "name": "Old Production Key",
  "status": "deprecated"
}