Update a private integrator Modify a tenant-private integrator's metadata, scopes, capabilities, or rate…

PUT /api/configuration/operator/integrators/private/{id}

Success: 200 OK

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

Overview

Rewrites the configuration of a private integrator belonging to your own tenant: its display metadata, the web origin its key may be used from, the scopes and capability flags stamped onto its tokens, its rate limits, and whether it is active. A private integrator is one your tenant created for itself with Create a private integrator, as opposed to a Gladstone-curated global one.

This is a full replacement, not a patch. Every field in the body is written unconditionally, so a field you omit is written as its JSON default — null for the strings, false for every boolean, 0 for both rate limits. Sending {"name": "Acme", "origin": "https://acme.example"} clears description, logoUrl and allowedScopes, sets canRead, canWrite, canDelete and isBillable to false, removes both rate limits, and sets isActive to false — which stops your integration authenticating altogether. Read the integrator first, change what you mean to change, and send the whole object back.

The tenant that owns the integrator is taken from your token, not from the body — there is no environmentId field to send, and you cannot move an integrator to another tenant. An id that belongs to another tenant, or to a global integrator, is rejected with 404, so this endpoint cannot be used to reach outside your own tenant.

Changes reach live traffic at different speeds:

Scopes and capability flags are baked into the JWT when a token is minted, so a token already in your integration's hands keeps its old claims until it expires. The next token carries the new values.
isActive false stops new tokens being issued, but can take up to five minutes to take effect. Access tokens already issued keep working until they expire.
Rate limits are read on every token request, so a change applies to the next call.

The API key is untouched: nothing is revoked, nothing is reissued, and no key value is returned. To replace the key itself, use Renew a private integrator's API key.

Endpoint

PUT {base_url}/api/configuration/operator/integrators/private/{id}

{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 integrator to update, from the `id` field of List the current tenant's private integrators. It must be a non-global integrator whose owning environment matches the one in your token; anything else — an unknown id, a global integrator, another tenant's private integrator — returns `404`.

Request body

Field	Type	Required	Description
`name`	string	Yes	The integrator's display name, shown to your operators when they pick an integration. Must be present and non-empty — omitting it, or sending `""` or `null`, fails validation with `400`. Not required to be unique. Maximum 255 characters, but a longer value fails with `500` rather than `400`.
`description`	string	No	Free-text explanation of what this integration does, for your own operators. Unbounded length. Omitting it or sending `null` clears the existing description — send the current value back to keep it.
`origin`	string	Yes	The single web origin (scheme and host, for example `https://booking.acme.example`) that browser-based use of this integrator's key is tied to. When a token request carries an `Origin` header it must equal this value — compared case-insensitively, ignoring one trailing slash — or the request is rejected with `401`. A token request with no `Origin` header skips the check, so this protects browser callers only, not server-to-server ones. One origin only; no list, no wildcard. Must be present and non-empty (`400` otherwise). Maximum 255 characters, but a longer value fails with `500` rather than `400`.
`logoUrl`	string	No	Absolute URL of a logo for the integrator. Maximum 500 characters; a longer value fails with `500` rather than `400`. The platform never fetches or validates it. Omitting it or sending `null` clears the existing value.
`isBillable`	boolean	No	Whether usage under this integrator is chargeable. Copied onto every new token as a `billable` claim, which is how usage is attributed. Private integrators are created with this set to `true` by default, so omitting it here flips a billable integration to non-billable — it does not preserve the existing value.
`allowedScopes`	string	No	The features this integrator may reach, as a JSON array serialised into a string — for example `"[\"FOH\",\"ONLINEBOOK\"]"`, not a JSON array in the body. Each entry is emitted twice on every new token, once as a features claim and once as a products claim, because gateway routes match on both. Nothing is validated at write time: if the string is not parseable as a JSON array of strings, new tokens carry no scope claims at all and every route rejects them with `403`. Omitting the field or sending `null` does the same — the integrator can still authenticate but can call nothing. Unbounded length. Entries are not checked against a list of known features, so a typo is accepted silently and simply never matches a route requirement.
`canRead`	boolean	No	Whether this integrator may issue `GET`, `HEAD` and `OPTIONS` requests. Emitted as a `can_read` claim on new tokens and enforced by every endpoint: a partner token without `can_read` true gets `403` with the plain-text body `Partner token lacks can_read capability.` Omitting this field sets it to false, which locks the integration out of every read endpoint from its next token onwards.
`canWrite`	boolean	No	Whether this integrator may issue `POST`, `PUT` and `PATCH` requests. Emitted as a `can_write` claim; a partner token without it true gets `403` with the body `Partner token lacks can_write capability.` Omitting this field sets it to false.
`canDelete`	boolean	No	Whether this integrator may issue `DELETE` requests. Emitted as a `can_delete` claim; a partner token without it true gets `403` with the body `Partner token lacks can_delete capability.` Only the `DELETE` method maps to this flag — a soft delete exposed as a `POST` or `PUT` is governed by `canWrite` instead. Omitting this field sets it to false.
`rateLimitPerMinute`	integer (int32)	No	Maximum token requests this integrator's API key may make in a one-minute window. Exceeding it returns `429` with a `Retry-After` header naming the seconds to wait. `0` means unlimited — and because omitting the field defaults it to `0`, leaving it out removes the limit rather than preserving it. Negative values are rejected with `400`. The window is a fixed calendar minute rather than a sliding one, so a burst straddling the boundary can consume two windows' worth. The limit applies to token requests only, not to the API calls you make with the token.
`rateLimitPerHour`	integer (int32)	No	Maximum token requests this integrator's API key may make in a one-hour window, checked only after the per-minute limit has passed. `0` means unlimited, which is also what omitting the field gives you. Negative values are rejected with `400`. Set above `rateLimitPerMinute` × 60 it can never bite; set below, it is the limit that actually applies.
`isActive`	boolean	No	Whether the integrator may be used at all. Key validation requires an active integrator, so setting this false stops the key minting tokens within five minutes, while access tokens already issued live out their term. Setting it back to true restores the key, because this endpoint never revokes anything. Omitting this field sets it to false and disables your integration — the most damaging mistake available on this endpoint. Note this is not the same as Delete a private integrator, which also revokes the key and cannot be undone.

Sample request

cURL

curl -X PUT '{base_url}/api/configuration/operator/integrators/private/{id}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "origin": "string",
  "logoUrl": "string",
  "isBillable": true,
  "allowedScopes": "string",
  "canRead": true,
  "canWrite": true,
  "canDelete": true,
  "rateLimitPerMinute": 1,
  "rateLimitPerHour": 1,
  "isActive": true
}'

Response fields

Field	Type	Description
`id`	integer (int32)	The integrator's identifier — the same value you passed in the path. Never reassigned by an update.
`name`	string	The name as persisted, echoing what you sent.
`description`	string	The description as persisted — `null` if you omitted the field, which clears it.
`origin`	string	The allowed origin as persisted, echoing what you sent.
`logoUrl`	string	The logo URL as persisted — `null` if you omitted the field.
`isGlobal`	boolean	Always `false` here: the update is rejected with `404` unless the target is a private integrator, and no endpoint can change this flag.
`isBillable`	boolean	The billable flag as persisted — `false` if you omitted the field, even though private integrators are created billable.
`environmentId`	integer (int32)	The identifier of the tenant environment that owns this integrator, resolved from your token rather than from the body. It is never null for a private integrator, and it is what allows keys from this integrator to mint tokens carrying tenant claims — which is why private integrators, unlike global ones, can be used for member login and member-token refresh.
`allowedScopes`	string	The scope string as persisted, byte for byte as you sent it — `null` if you omitted the field. It is not parsed, so this confirms what was written, not that it is usable.
`canRead`	boolean	The read capability as persisted — `false` if you omitted the field, which blocks every `GET` from the next token onwards.
`canWrite`	boolean	The write capability as persisted — `false` if you omitted the field.
`canDelete`	boolean	The delete capability as persisted — `false` if you omitted the field.
`rateLimitPerMinute`	integer (int32)	The per-minute budget as persisted — `0`, meaning unlimited, if you omitted the field.
`rateLimitPerHour`	integer (int32)	The per-hour budget as persisted — `0`, meaning unlimited, if you omitted the field.
`isActive`	boolean	The active flag as persisted. Check it on every response: `false` means the integrator can no longer obtain tokens, and it is `false` whenever the field was omitted from the body.
`createdOn`	string (date-time)	UTC timestamp the integrator was created. Unchanged by this call.
`modifiedOn`	string (date-time)	UTC timestamp of this update, set server-side. Always populated in a successful response from this endpoint.

Sample response

200 OK

{
  "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	Either validation failed — `name` or `origin` missing, empty or null, or a negative rate limit, returned as a validation problem document (`application/problem+json`) with an `errors` map keyed by field name — or the tenant environment could not be resolved from your token, in which case the body is the plain string `Could not resolve tenant environment.` Nothing is written in either case.
`404`	Not found	No integrator exists with that id, or it is a global integrator, or it belongs to a different tenant. All three are indistinguishable: the response has no body. Contrary to the endpoint summary, a global or cross-tenant target is a `404`, not a `400`.
`500`	Internal server error	An unexpected server-side failure, including a `name` or `origin` over 255 characters or a `logoUrl` over 500 — those limits are not validated up front, so they surface as a `500` rather than a `400`. The body is empty and nothing is written.

This page as markdown · All pages · llms.txt