API reference · Keys
Rotate a key with a grace period
POST/api/keys/{id}/rotateSigned in session
Mints a replacement carrying the same name, scopes, expiry, allowlist, organization and policy, and leaves the old key working until graceUntil. Revoking a production key with no window is how outages happen, so this is the supported way to change one. The replacement is held by the caller: an organization key rotated by an admin or owner who did not hold it spends as that admin or owner from then on, inside their own budget.
Parameters
| Field | Type | What it is |
|---|---|---|
| id (path)required | integer | The key id. |
Request body
application/json, optional
| Field | Type | What it is |
|---|---|---|
| graceSeconds | integer | 0 to 2592000. Default 86400. |
Example
{
"graceSeconds": 0
}Answer 201
Rotated.
| Field | Type | What it is |
|---|---|---|
| key | string | The replacement, shown exactly once. |
| id | integer | |
| retiredKeyId | integer | |
| graceUntil | integer | Unix ms. The old key stops working here. |
| note | string |
Errors
- 400OpenAI shaped error.
- 401OpenAI shaped error.
- 404OpenAI shaped error.
- 409OpenAI shaped error.
Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.