Rotate an API key
POST
/api/api-keys/{id}/rotate
deprecated
Requires: ApiKeyAuthorization.ApiKeys, ApiKeyAuthorization.ApiKeys.Revoke, merchant scope.
Mints a replacement owned by the same user and merchant, with the same access, and returns it with its value revealed. This is the only time that value is shown. The key being rotated keeps authenticating for an overlap window (24 hours by default, seven days at most) so the integration can deploy the replacement without an outage, and is then refused with KEY_REVOKED. To end the overlap sooner, revoke the rotated key: that takes effect on the very next request. Gated on the same permission as revoke, because it is the same decision about the same credential. Refused for a key that has already been revoked or already been rotated. Also refused for a suspended key, because a working replacement with the same access would route around the suspension. Reinstate the key first, or revoke it and create a new key. Who may call this: the key's owner, an administrator, or a caller that holds the ApiKeyAuthorization.ApiKeys.CreateForUser permission and has authority over the merchant the key belongs to, when the key's owner is an active user of that merchant. That last group is the same authority that provisions a key through POST /api/api-keys/for-user, so a reseller can manage the keys it provisioned for its merchants' users. The endpoint's own permission is required as well. Any other caller gets the same 404 as a key that does not exist.
Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.
Example request
Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.
The request body is a RotateApiKeyDto. See the Request body section below for its fields.
Parameters
Request body
application/json
, required
| Field | Type | Description |
|---|---|---|
overlapHours
required |
integer (int32) | How many hours the replaced key should keep authenticating, or `null` for the configured
default (24 hours).
nullablemin 0
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
expireAt
required |
string (date-time) | When the replacement should expire, or `null` to give it the same term the replaced key
was originally granted, measured from now.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
reason
required |
string | A reason recorded against the replaced key, used only when the rotation cuts over immediately
and therefore revokes it in the same operation.
nullablemax length 256
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
This request body has no documented fields.
Responses
Errors
A failed request returns the platform error envelope. The
error reference lists every value
error.code can carry and shows the four response shapes.
Authentication
ApiKeywith scopes