Renew a private integrator's API key Atomically revoke the current key and issue a fresh one, returning the…
POST /api/configuration/operator/integrators/private/{id}/renew-key
Success: 200 OK
- Products: Operator (
FOH) - Features: Front of House Generic Access (
FOHGENERIC)
Overview
Rotates the API key of one of your tenant's private integrators: the current key is revoked and a new one issued in a single atomic operation, so the integrator is never left with two live keys or none.
The full plaintext key is in the apiKey field of this response and is returned exactly once.
This response is the only place it ever appears: no list or read endpoint returns a
plaintext key, and every later read exposes only the 8-character prefix. Write it to your secret
store before you do anything else with the response — if you lose it, your only recovery is to call
this endpoint again, which rotates the key a second time.
Rotation is not instant on either side, and that is the trap. The revocation and the new key both take effect for token issuance asynchronously. Allow up to 120 seconds; the delay has been observed at anywhere from about 4 seconds to the full 120. For that window the old key may still mint tokens and the new key may still be rejected. Do not deploy the new key and immediately tear down the old one; keep both configured, retry the first token request with the new key, and only then discard the old.
Tokens already minted from the old key are unaffected — they remain valid until they expire. Revocation stops new tokens being issued; it does not invalidate outstanding ones.
If the integrator currently has no active key — for example because it was revoked earlier — this call simply issues one, with no error.
This endpoint works only on private integrators belonging to your own tenant. To rotate a key you hold against a Gladstone-curated global integrator, call Activate a global integrator again instead.
Endpoint
POST {base_url}/api/configuration/operator/integrators/private/{id}/renew-key
{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | integer (int32) | Yes | The private integrator to rotate, taken from id in List the current tenant's private integrators. It must be a private integrator belonging to your own tenant: an id that does not exist, one belonging to a global integrator, or one belonging to another tenant all return the same 404, with no body to tell them apart. |
Sample request
curl -X POST '{base_url}/api/configuration/operator/integrators/private/{id}/renew-key' \
-H 'Authorization: Bearer {accessToken}' \
-H 'X-Use-SSO: true'Response fields
| Field | Type | Description |
|---|---|---|
apiKey | string | The new plaintext API key, in the form gsk_sV_ followed by 32 random alphanumeric characters. Returned exactly once, here. No other endpoint returns a plaintext key, so once you discard this response the value is unrecoverable through the API. It is guaranteed to differ from the key it replaces. It may not be accepted for token issuance for up to two minutes — see the Overview. |
apiKeyPrefix | string | The first 8 characters of apiKey, safe to display and log. It is the only part of a key that any later read returns, so use it to confirm which key a given system is holding. |
id | integer (int32) | The integrator's identifier — the same value you passed in the path. The API key itself has no publicly returned identifier, so apiKeyPrefix is the only way to distinguish one key from another. |
name | string | The integrator's display name, as set when the private integrator was created. Not changed by this call and not unique. |
description | string | The integrator's description, as set when it was created. Null if none was given. |
origin | string | The one web origin this integrator is allowed to call from. When you request a token with the new key and send an Origin header, it must match this value or the token request is rejected. Not changed by rotating the key. |
logoUrl | string | Absolute URL of the integrator's logo, or null if none was set. |
isGlobal | boolean | Always false here — a global integrator is rejected with 404 before any rotation happens. |
isBillable | boolean | Whether usage under this integrator is chargeable. Carried as a billable claim on tokens minted from the new key; unchanged by rotation. |
environmentId | integer (int32) | The tenant environment the integrator belongs to. For a private integrator this is always your own environment — an integrator whose environment differs from the one resolved from your token returns 404 — so it is never null here, unlike on a global integrator. |
allowedScopes | string | The features this integrator may reach, held as a JSON array encoded into a string rather than as a JSON array. Each entry becomes both a features claim and a products claim on tokens minted from the new key. Rotation does not change it, so if tokens from the old key worked, tokens from the new one will carry the same scopes. |
canRead | boolean | Whether the integrator may perform read operations, carried as a can_read claim on tokens minted from the new key. Unchanged by rotation. |
canWrite | boolean | Whether the integrator may perform write operations, carried as a can_write claim. Unchanged by rotation. |
canDelete | boolean | Whether the integrator may perform delete operations, carried as a can_delete claim. Unchanged by rotation. |
rateLimitPerMinute | integer (int32) | The per-minute request budget recorded against the integrator. Unchanged by rotation. |
rateLimitPerHour | integer (int32) | The per-hour request budget recorded against the integrator. Unchanged by rotation. |
isActive | boolean | Whether the integrator record itself is enabled. Rotating a key does not change it, and — unlike activating a global integrator — this call will not reactivate a disabled integrator. If this comes back false, the new key exists but the integrator is switched off. |
createdOn | string (date-time) | UTC timestamp the integrator record was created, not the timestamp of this rotation. The new key's own creation time is not returned. |
modifiedOn | string (date-time) | UTC timestamp the integrator record was last modified. Rotation does not count as a change to the integrator, so this value does not move when you renew a key and may be null. Do not use it to detect that a rotation happened. |
Sample response
{
"apiKey": "string",
"apiKeyPrefix": "string",
"id": 12345,
"name": "string",
"description": "string",
"origin": "string",
"logoUrl": "string",
"isGlobal": true,
"isBillable": true,
"environmentId": 12345,
"allowedScopes": "string",
"canRead": true,
"canWrite": true,
"canDelete": true,
"rateLimitPerMinute": 1,
"rateLimitPerHour": 1,
"isActive": true,
"createdOn": "2026-08-14T19:00:00Z",
"modifiedOn": "2026-08-14T19:00:00Z"
}Errors
| Status | Meaning | When |
|---|---|---|
400 | Bad request | The tenant environment could not be resolved from your token. The body is the plain string Could not resolve tenant environment. Nothing is revoked and no key is issued. |
404 | Not found | No integrator exists with that id, or it is a global integrator, or it belongs to a different tenant. The response has no body. Nothing is revoked and no key is issued. |
500 | Internal server error | An unexpected server-side failure. The body is empty. The revoke and the new key succeed or fail together, so a failure during rotation leaves your existing key intact — but a failure after the rotation completes, while returning the response, loses the plaintext key permanently. If you get a 500, list the integrator and compare the key prefix before deciding whether to call again. |
503 | Service unavailable | Not returned by this endpoint itself. A 503 reaching you comes from the hosting platform in front of it, so the rotation may or may not have happened; check the key prefix before retrying. |