Create a global integrator Registers a new global integrator visible to all tenants
POST /api/configuration/admin/integrators
Success: 201 Created
- Products: not restricted by product
- Features: Gladstone Admin Areas (
ADMIN)
Overview
Registers a global integrator — a partner record that every tenant can see and opt into. This endpoint only creates the catalogue entry; it does not issue an API key. A tenant gets a key by calling Activate a global integrator against the id returned here.
The call requires an ADMIN feature claim on your token. Anything else is rejected with 403 before the request body is even read, so this endpoint is reserved for Gladstone Support rather than for tenants or their integrators.
The integrator is created with isGlobal set to true, environmentId left null and isActive set to true — none of those three are yours to set. The system allocates the integer id; you cannot choose it.
This call is not idempotent, and integrator names are not unique. Posting the same body twice produces two separate catalogue entries with different ids, both visible to every tenant. Check the existing catalogue before retrying a request that timed out.
The allowedScopes, canRead/canWrite/canDelete and rate-limit values set here are copied onto every JWT minted from an API key issued under this integrator, so getting them wrong is not a cosmetic problem — it changes what the integration can do.
Endpoint
POST {base_url}/api/configuration/admin/integrators
{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The display name of the integrator, as shown to tenants browsing the catalogue. Maximum 255 characters, and it may not be empty or whitespace-only. Names are not checked for uniqueness, so two integrators can share a name; tell them apart by id. |
description | string | No | Free-text explanation of what the integration does, shown alongside the name. No length limit. Omit it, or send null, to leave it blank. |
origin | string | Yes | The exact web origin the integration calls from, for example https://app.example.com. Maximum 255 characters, may not be empty. This is enforced at token-issue time: if a token request carries an Origin header, it must match this value or the request is rejected with 401. The comparison ignores case and a trailing slash, and it is an exact match — wildcards and multiple origins are not supported. A token request that sends no Origin header at all skips the check entirely. |
logoUrl | string | No | Absolute URL of the integrator's logo, used when the catalogue is presented to tenants. Maximum 500 characters. Omit it, or send null, to show no logo. The URL is stored as given and is not fetched or validated. |
isBillable | boolean | No | Whether usage under this integrator is chargeable. Emitted as a billable claim on every token issued under this integrator. Defaults to false for global integrators when omitted. |
allowedScopes | string | No | The features the integrator may reach, as a JSON array encoded into a string — for example "[\"FOHGENERIC\"]". Use the feature codes listed in the features line of each endpoint page. At token-issue time each entry in the array is emitted as both a features claim and a products claim; API routes require both, so an integrator with no scopes gets a token that every route rejects with 403. Beware: if the string is not valid JSON nothing reports it and you get the same empty-claims token, with no error at creation time and no error at token issue. Omitting the field has the same effect. |
canRead | boolean | No | Whether the integrator may perform read operations. Emitted as a can_read claim on every token issued under this integrator. Defaults to false when omitted. Send true explicitly. |
canWrite | boolean | No | Whether the integrator may perform write operations. Emitted as a can_write claim on every token issued under this integrator. Defaults to false when omitted, as with canRead — send it explicitly. |
canDelete | boolean | No | Whether the integrator may perform delete operations. Emitted as a can_delete claim on every token issued under this integrator. Defaults to false when omitted, as with canRead — send it explicitly. |
rateLimitPerMinute | integer (int32) | No | The per-minute request budget recorded against the integrator. Must be 0 or greater; a negative value is rejected with 400. Defaults to 0 when omitted. |
rateLimitPerHour | integer (int32) | No | The per-hour request budget recorded against the integrator. Must be 0 or greater; a negative value is rejected with 400. Defaults to 0 when omitted. |
Sample request
curl -X POST '{base_url}/api/configuration/admin/integrators' \
-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
}'Response fields
| Field | Type | Description |
|---|---|---|
id | integer (int32) | The integer identifier the system allocated for the new integrator. This is the value a tenant passes to the activate endpoint, and the value you use to update or delete the integrator later. You cannot choose it. |
name | string | The integrator's display name as stored — echoes what you sent. |
description | string | The description as stored, or null if you did not send one. |
origin | string | The allowed origin as stored. Token requests carrying a mismatched Origin header are rejected with 401. |
logoUrl | string | The logo URL as stored, or null if you did not send one. |
isGlobal | boolean | Always true for an integrator created here. It is what makes the integrator visible to every tenant, and it is set for you, not by your request. |
isBillable | boolean | Whether usage under this integrator is chargeable — echoes what you sent, or false if you omitted it. Carried as a billable claim on every token issued under this integrator. |
environmentId | integer (int32) | Always null for a global integrator, because the catalogue entry belongs to no single tenant. Note the consequence: tokens minted from a global integrator's key carry no tenant claims, so they cannot reach tenant-scoped endpoints and cannot be used for member login or member-token refresh. Only a private integrator, which does carry an environmentId, can do that. |
allowedScopes | string | The scope string as stored. Verify it is a valid JSON array before handing the integrator to a tenant: an unparseable or empty value produces tokens with no features or products claims, which every API route rejects with 403. |
canRead | boolean | Whether the integrator may read — echoes what you sent, or false if omitted. Carried as a can_read claim on tokens issued under this integrator. |
canWrite | boolean | Whether the integrator may write — echoes what you sent, or false if omitted. Carried as a can_write claim. |
canDelete | boolean | Whether the integrator may delete — echoes what you sent, or false if omitted. Carried as a can_delete claim. |
rateLimitPerMinute | integer (int32) | The per-minute budget as stored — echoes what you sent, or 0 if omitted. |
rateLimitPerHour | integer (int32) | The per-hour budget as stored — echoes what you sent, or 0 if omitted. |
isActive | boolean | Always true on creation. It becomes false when the integrator is deleted. |
createdOn | string (date-time) | UTC timestamp the integrator was created, set for you. Not normally null. |
modifiedOn | string (date-time) | UTC timestamp of the last update. Null on a freshly created integrator, because nothing has modified it yet. |
Sample response
{
"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 | name or origin is missing, empty or whitespace-only, or a rate limit is negative. The body is a validation problem document (application/problem+json) with an errors map naming the offending field. |
403 | Forbidden | Your token does not carry the ADMIN feature claim. Returned before the body is inspected, with no message. |
500 | Internal server error | An unexpected server-side failure while saving the integrator. The body is empty. |