Rotate an API key

Rotate an API key’s token. Issues a new secret token and returns it — the new token is only shown once, so store it securely.

Self-only: You can only rotate the API key that was used to authenticate this request. Attempting to rotate a different key returns 403 Forbidden.

Grace period: When enabled for your organization, the previous token remains valid after rotation, giving you time to deploy the new token without downtime. Pass grace_period_minutes (integer, 0–1440, default 30) to control how long the old token stays valid. Set to 0 to immediately invalidate the old token. The grace_period_ends_at field in the response confirms the exact time the old token will stop working.

Expiration: Optionally provide a new expires_at date (ISO 8601, up to 5 years). Defaults to 90 days from now if omitted. Dates in the past are rejected.

Typical rotation workflow:

1. Call this endpoint to get a new token (optionally with a custom grace_period_minutes).
2. Deploy the new token to your systems.
3. The old token continues working for grace_period_minutes (if grace period is enabled).
4. After the grace period, the old token is automatically invalidated.

POST /v1/api_keys/{id}/rotate

Rotate an API key

cURL

curl --request POST \
  --url https://api.rootly.com/v1/api_keys/{id}/rotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '
{
  "data": {
    "type": "api_keys",
    "attributes": {
      "expires_at": "2023-11-07T05:31:56Z",
      "grace_period_minutes": 30
    }
  }
}
'

200

{
  "data": {
    "id": "<string>",
    "type": "api_keys",
    "attributes": {
      "name": "<string>",
      "kind": "personal",
      "created_at": "<string>",
      "updated_at": "<string>",
      "token": "<string>",
      "description": "<string>",
      "role_id": "<string>",
      "on_call_role_id": "<string>",
      "expires_at": "<string>",
      "last_used_at": "<string>",
      "grace_period_ends_at": "<string>"
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id · string · required

Body

application/vnd.api+json

data · object · required

Show child attributes

Response

200

application/vnd.api+json

API key rotated

data · object · required

Show child attributes