Activate a global integrator for the current tenant Issue a fresh API key against a global integrator and…
POST /api/configuration/operator/integrators/{id}/activate
Success: 200 OK
- Products: Operator (
FOH) - Features: Front of House Generic Access (
FOHGENERIC)
Overview
Opts your tenant into a Gladstone-curated global integrator and issues an API key for it. The integrator itself is created by Gladstone Support; this call is how a tenant starts using one.
The full plaintext API key is in the apiKey field of this response and is returned exactly once. No endpoint returns it again, so persist it to your secret store before doing anything else with the response. Treat it as a password: it grants your integration's full access to this tenant.
Calling this a second time is destructive, not idempotent. Every call revokes whatever active key your tenant already held for this integrator — deliberately, in case that key had leaked — and issues a brand-new one. A retry after a timeout therefore invalidates the key the first attempt returned, which you may not have captured. Treat this as a key-rotation operation and call it only when you intend to rotate.
The integrator's scopes, capability flags and rate limits are fixed by Gladstone Support when the integrator is created; you cannot vary them per tenant here. If the integrator was marked inactive, this call reactivates it.
One limitation worth knowing before you build: tokens carry tenant claims only when the integrator has an environmentId, and that is always null for a global integrator. Keys issued here therefore mint API-only tokens without tenant claims, and cannot be used for member login or member-token refresh. Use a private integrator for those flows.
Endpoint
POST {base_url}/api/configuration/operator/integrators/{id}/activate
{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 identifier of the global integrator to activate, taken from the global integrator catalogue. It must belong to an integrator with isGlobal true — an id that does not exist, or that belongs to a private integrator, returns 404. |
Sample request
curl -X POST '{base_url}/api/configuration/operator/integrators/{id}/activate' \
-H 'Authorization: Bearer {accessToken}' \
-H 'X-Use-SSO: true'Response fields
| Field | Type | Description |
|---|---|---|
apiKey | string | The full plaintext API key, in the form gsk_sV_ followed by 32 random characters. Returned exactly once, here — no endpoint returns it again, so store it immediately. Any key previously issued to your tenant for this integrator is revoked by this call; it can keep working for a short time before it stops. |
apiKeyPrefix | string | The first 8 characters of apiKey, safe to display and log. It is the only part of the key that later reads return, so use it to confirm which key a system is holding. |
id | integer (int32) | The integrator's identifier — the same value you passed in the path, not a new key id. The API key itself has no publicly returned identifier. |
name | string | The integrator's display name, as set by Gladstone Support. Not unique across the catalogue. |
description | string | The integrator's description, as set by Gladstone Support. Null if none was given. |
origin | string | The one web origin this integrator is allowed to call from. When you request a token and send an Origin header, it must match this value — compared case-insensitively and ignoring a trailing slash — or the token request is rejected with 401. A token request with no Origin header skips the check. You cannot change this value; ask Gladstone Support to. |
logoUrl | string | Absolute URL of the integrator's logo, or null if none was set. |
isGlobal | boolean | Always true here, since only global integrators can be activated through this endpoint. |
isBillable | boolean | Whether usage under this integrator is chargeable. Set by Gladstone Support and carried as a billable claim on every token minted from the new key. |
environmentId | integer (int32) | Always null for a global integrator — the catalogue entry belongs to no tenant, even though the API key this call issued does belong to yours. This is why keys from a global integrator produce tokens without tenant claims. |
allowedScopes | string | The features this integrator may reach, returned as a JSON array encoded into a string. Each entry becomes both a features claim and a products claim on tokens minted from the new key, and API routes require both. If this comes back null, empty, or as anything that is not a valid JSON array, tokens from your new key will carry no scope claims and every route will reject them with 403 — check this field before you conclude your key is broken. |
canRead | boolean | Whether the integrator may perform read operations. Carried as a can_read claim on tokens minted from the new key. Fixed by Gladstone Support; not variable per tenant. |
canWrite | boolean | Whether the integrator may perform write operations. Carried as a can_write claim on tokens minted from the new key. Fixed by Gladstone Support. |
canDelete | boolean | Whether the integrator may perform delete operations. Carried as a can_delete claim on tokens minted from the new key. Fixed by Gladstone Support. |
rateLimitPerMinute | integer (int32) | The token requests your new key may make in a one-minute window, set by Gladstone Support. Exceeding it returns 429 with a Retry-After header. 0 means unlimited. The budget is counted per key, so it is yours alone and is not shared with other tenants using the same integrator. |
rateLimitPerHour | integer (int32) | The token requests your new key may make in a one-hour window, checked after the per-minute limit passes. 0 means unlimited. Both limits apply only to token requests, not to the API calls you make with the token you receive. |
isActive | boolean | Always true after a successful activation — if the integrator had been marked inactive, this call turns it back on. |
createdOn | string (date-time) | UTC timestamp the integrator was created by Gladstone Support, not the timestamp of your activation. |
modifiedOn | string (date-time) | UTC timestamp the integrator was last modified. It is updated by this call only when the integrator had to be reactivated; otherwise it keeps its previous value and may be null. |
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. No key is issued and no existing key is revoked. |
404 | Not found | No integrator exists with that id, or the id belongs to a private integrator rather than a global one. The response has no body. |
500 | Internal server error | An unexpected server-side failure. The body is empty. Because the old key is revoked before the new one is issued, a 500 can leave you with no working key — list the integrator to check its prefix and activate again if necessary. |