# Rotate API key

Rotates the secret key for the specified API key. Returns a new secret in the rotate_secret field, which becomes valid within a few seconds. The previous secret remains valid during the rotation period and expires once the period ends. This endpoint requires an account-level API key.

Endpoint: POST /api-keys/rotate
Version: 2.0.0
Security: bearerAuth

## Request fields (application/json):

  - `id` (string, required)
    Unique API key identifier.
    Example: "akey_163f12ss514120a58gt851c5d338d072"

  - `period_seconds` (integer, required)
    Duration of the rotation period in seconds during which both the new and previous secrets remain valid.
    Example: 86400

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique API key identifier.
    Example: "akey_163f12ss514120a58gt851c5d338d072"

  - `name` (string, required)
    API key name.
    Example: "Production API Key"

  - `description` (string)
    API key description.
    Example: "Used for production environment"

  - `rotate_secret` (string, required)
    New secret value used for authentication.
    Example: "asec_********************"

  - `rotate_at` (string, required)
    Date and time when the previous secret expires and rotate_secret becomes the only valid secret.
    Example: "2024-01-01T10:00:00.000000Z"

  - `channel_ids` (array)
    Channel IDs that the API key has access to.
    Example: ["chn_01ARZ3NDEKTSV4RRFFQ69G5FAV","chn_01KTXHKMEXBM5JMEQAHBCV6802"]

  - `permissions` (array, required)
    Permissions granted to the API key.
    Example: ["payment:create","payment:read"]

  - `created_at` (string, required)
    Date and time of API key creation.
    Example: "2024-01-01T10:00:00.000000Z"

  - `updated_at` (string, required)
    Date and time of the last API key update.
    Example: "2024-01-02T15:00:00.000000Z"

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: "One or more fields failed validation due to constraints"

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

  - `context.constraints` (object, required)
    Failed constraints keyed by the field name.
    Example: {"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: "Credentials are invalid or missing"

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: "Permission denied"

## Response 422 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "KEY_IN_ROTATION"

  - `message` (string, required)
    Message describing the error.
    Example: "The request conflicts with the current state"

  - `context` (object)
    Additional error context.