Revoke a private integrator's API key Immediately invalidate the active API key for a private integrator…
POST /api/configuration/operator/integrators/private/{id}/revoke-key
- Products: Operator (
FOH) - Features: Front of House Generic Access (
FOHGENERIC)
Overview
Immediately invalidates the API key currently issued to your tenant for a private integrator, without deleting the integrator or losing any of its configuration. The key is marked Revoked with a revocation timestamp; it can never be un-revoked.
What stops working, and what does not. An API key is only ever presented to one place: the partner token endpoint, in the X-Partner-Api-Key header. Once the key is revoked, every call to that endpoint using it is rejected with 401 and an empty body — that covers both requesting a fresh access token and exchanging a refresh token for a new one, because both go through the same key check. Access tokens already issued are not affected. They are self-contained JWTs, validated by signature and expiry rather than by re-checking the key, so an integration already holding a valid access token keeps working normally until that token expires. The practical effect is that your integration continues to function and then fails at its next token request, which can be some minutes after you call this endpoint.
Revocation usually takes effect immediately, but can take up to 5 minutes. In the worst case the revoked key can still obtain tokens for up to 5 minutes after a successful revoke. The 5-minute window is fixed and you cannot shorten it. Treat 5 minutes as the guaranteed upper bound during which the revoked key may still mint tokens, not as the expected delay.
This is not reversible. There is no un-revoke. To get the integration working again, call Renew a private integrator's API key, which issues a fresh key and returns its plaintext exactly once. If you already know you want a replacement key, call the renew endpoint instead of this one — it revokes and reissues in a single step, so the integrator is never left with no usable key.
The integrator record itself is untouched: it stays active, and its name, origin, scopes, capability flags and rate limits are all preserved. To retire the integrator as well, use Delete a private integrator instead.
A successful call returns 204 No Content with no body. Nothing in the response identifies which key was revoked, so if you need to confirm the change, list your private integrators and check that the integrator now reports no active key prefix.
Endpoint
POST {base_url}/api/configuration/operator/integrators/private/{id}/revoke-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 integrator whose key you want to revoke, taken from the list of your private integrators. The key that gets revoked is the one matching this integrator and the tenant environment resolved from your token, so you can never revoke another tenant's key with this call. Note that this endpoint does not check whether the integrator is private — passing the id of a global integrator your tenant has activated revokes your tenant's key for that global integrator instead, which is almost certainly not what you intended. |
Sample request
curl -X POST '{base_url}/api/configuration/operator/integrators/private/{id}/revoke-key' \
-H 'Authorization: Bearer {accessToken}' \
-H 'X-Use-SSO: true'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. |
404 | Not found | No integrator with that id holds an active, unexpired key in your tenant environment. This covers three distinct cases you cannot tell apart from the response: the id does not exist, the integrator belongs to another tenant, or its key has already been revoked. Calling this endpoint twice therefore returns 204 then 404 — the second 404 means "already revoked", not "failed". The response has no body. |
500 | Internal server error | An unexpected server-side failure. The body is empty. A 500 may still have left the key revoked — verify before retrying. |