Gainsight User Management API Guide

Auth method: API Key (Access Key) passed as HTTP header; SCIM endpoints use Bearer token issued via OAuth 2.0 client credentials flow with the IdP (Okta/Entra).

Setup steps

1. Log in to Gainsight NXT as an admin and navigate to Administration > Integrations > Connector 2.0 or API Access.
2. Generate an Access Key (API key) for the integration user.
3. Include the key in all REST API requests as the header: 'Accesskey: '.
4. For SCIM: configure SAML SSO first (required prerequisite), then enable SCIM provisioning in Administration > User Management > SCIM.
5. Copy the SCIM Base URL and Bearer Token from the Gainsight SCIM settings page and paste into your IdP (Okta or Entra AD) SCIM configuration.

Required scopes

List Users

• Method: GET
• URL: https://{{domain}}.gainsightcloud.com/v1/users
• Watch out for: Inactive users are included by default; filter with isActive=true if needed.

Request example

GET /v1/users?page=1&pageSize=100
Accesskey: <your-access-key>

Response example

{
  "result": true,
  "data": [
    {"userId":"u123","email":"jane@acme.com","firstName":"Jane","isActive":true}
  ],
  "totalCount": 1
}

Get User by ID

• Method: GET
• URL: https://{{domain}}.gainsightcloud.com/v1/users/{userId}
• Watch out for: Returns 404 if userId does not exist in the tenant.

Request example

GET /v1/users/u123
Accesskey: <your-access-key>

Response example

{
  "result": true,
  "data": {"userId":"u123","email":"jane@acme.com","firstName":"Jane","role":"Admin"}
}

Create User

• Method: POST
• URL: https://{{domain}}.gainsightcloud.com/v1/users
• Watch out for: Role must exactly match an existing role name; mismatches return a 400 error.

Request example

POST /v1/users
Accesskey: <your-access-key>
Content-Type: application/json
{
  "email":"new@acme.com","firstName":"New","lastName":"User","role":"Standard User"
}

Response example

{
  "result": true,
  "data": {"userId":"u456","email":"new@acme.com","isActive":true}
}

Update User

• Method: PUT
• URL: https://{{domain}}.gainsightcloud.com/v1/users/{userId}
• Watch out for: Gainsight REST uses PUT (full or partial update behavior varies by version); confirm with your tenant's API version.

Request example

PUT /v1/users/u456
Accesskey: <your-access-key>
Content-Type: application/json
{
  "firstName":"Updated","isActive":true
}

Response example

{
  "result": true,
  "data": {"userId":"u456","firstName":"Updated"}
}

Deactivate / Delete User

• Method: DELETE
• URL: https://{{domain}}.gainsightcloud.com/v1/users/{userId}
• Watch out for: DELETE typically deactivates the user rather than permanently removing them; data retention policies apply.

Request example

DELETE /v1/users/u456
Accesskey: <your-access-key>

Response example

{
  "result": true,
  "message": "User deactivated successfully."
}

SCIM Get Users

• Method: GET
• URL: https://{{domain}}.gainsightcloud.com/scim/v2/Users
• Watch out for: SCIM endpoint is separate from the REST API base URL and uses a different Bearer token.

Request example

GET /scim/v2/Users?startIndex=1&count=100
Authorization: Bearer <scim-token>

Response example

{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults":1,
  "Resources":[{"id":"u123","userName":"jane@acme.com","active":true}]
}

SCIM Create User

• Method: POST
• URL: https://{{domain}}.gainsightcloud.com/scim/v2/Users
• Watch out for: SAML SSO must be fully configured before SCIM provisioning will function.

Request example

POST /scim/v2/Users
Authorization: Bearer <scim-token>
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"new@acme.com","name":{"givenName":"New","familyName":"User"}
}

Response example

{
  "id":"u789","userName":"new@acme.com","active":true,
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"]
}

SCIM Update User (Patch)

• Method: PATCH
• URL: https://{{domain}}.gainsightcloud.com/scim/v2/Users/{id}
• Watch out for: Deprovisioning via SCIM sets active=false; it does not hard-delete the user record.

Request example

PATCH /scim/v2/Users/u789
Authorization: Bearer <scim-token>
{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations":[{"op":"replace","path":"active","value":false}]
}

Response example

{
  "id":"u789","active":false,"userName":"new@acme.com"
}

• Rate limits: Gainsight enforces API rate limits per tenant. Official documentation does not publicly disclose exact numeric thresholds; limits are communicated per contract/plan.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: HTTP 429 is returned when limits are exceeded. Gainsight recommends exponential back-off. Exact limits are not published in public docs.
• Pagination method: offset
• Default page size: 100
• Max page size: 1000
• Pagination pointer: page / pageSize (REST); startIndex / count (SCIM)

• Webhooks available: No
• Webhook notes: Gainsight NXT does not expose native outbound webhooks for user-management events (user created, deactivated, etc.) in its publicly documented API surface.
• Alternative event strategy: Use Gainsight's Connectors / Rules Engine or poll the REST API on a schedule to detect user changes. SCIM provisioning from an IdP (Okta/Entra) is the recommended push-based provisioning mechanism.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://{{domain}}.gainsightcloud.com/scim/v2

• Supported operations: GET /Users (list), GET /Users/{id}, POST /Users (create), PUT /Users/{id} (replace), PATCH /Users/{id} (update/deactivate), DELETE /Users/{id}, GET /Groups, POST /Groups, PATCH /Groups/{id}, GET /ServiceProviderConfig

Limitations:

• SAML SSO must be configured and active before SCIM can be enabled.
• Only Okta and Microsoft Entra ID (Azure AD) are officially supported IdPs for SCIM.
• Google Workspace and OneLogin are not supported for SCIM.
• Gainsight inSided (Community product) does NOT support SCIM provisioning.
• Custom fields are supported in SCIM but must be pre-defined in Gainsight admin before mapping.
• SCIM Bearer token is static and generated in the Gainsight UI; rotation requires manual regeneration.
• Enterprise plan required; not available on lower tiers.

Three primary automation scenarios are supported by the documented API surface.

For direct REST provisioning: POST to /v1/users with email, firstName, lastName, and role. The role value must exactly match an existing role name in the tenant (case-sensitive); a mismatch returns HTTP 400. Capture the returned userId immediately - it is the stable identifier for all subsequent PUT/DELETE calls on that record.

For IdP-driven lifecycle via SCIM (Okta or Entra ID only): SAML SSO must be fully configured before SCIM can be enabled - this is a hard prerequisite, not a soft dependency. Copy the SCIM Base URL and static Bearer token from Gainsight admin, paste into your IdP, then enable Create, Update, and Deactivate provisioning actions. The SCIM token is static; if regenerated in Gainsight, the IdP configuration must be updated immediately or all provisioning calls will fail with auth errors.

For bulk deactivation via REST: paginate GET /v1/users?isActive=true&pageSize=1000, identify target users, then send DELETE /v1/users/{userId} per user. Note that DELETE deactivates rather than permanently removes the user record - verify hard-deletion behavior with Gainsight support if compliance requirements mandate it.

Provision a new internal user via REST API

1. Generate an Access Key in Gainsight Administration > API Access.
2. POST to /v1/users with required fields: email, firstName, lastName, role.
3. Capture the returned userId for future update or deactivation calls.
4. Optionally PATCH/PUT to add customAttributes or assign to groups.

Watch out for: The role field must exactly match an existing role name in the tenant; a mismatch returns HTTP 400.

Automate user lifecycle via SCIM with Okta

1. Configure SAML SSO between Gainsight and Okta (required prerequisite).
2. In Gainsight admin, enable SCIM and copy the SCIM Base URL and Bearer Token.
3. In Okta, add the Gainsight app, set provisioning to SCIM 2.0, paste the Base URL and Bearer Token.
4. Enable Okta provisioning features: Create Users, Update User Attributes, Deactivate Users.
5. Assign users/groups in Okta; Okta will POST to /scim/v2/Users to provision them in Gainsight.

Watch out for: SCIM token is static; if regenerated in Gainsight, the Okta configuration must be updated immediately or provisioning will break.

Bulk deactivate users via REST API

1. GET /v1/users?isActive=true&pageSize=1000 to retrieve all active users.
2. Iterate through the list and identify users to deactivate (e.g., by department or role).
3. For each target user, send DELETE /v1/users/{userId} or PUT /v1/users/{userId} with isActive=false.
4. Implement exponential back-off on HTTP 429 responses due to undisclosed rate limits.

Watch out for: DELETE deactivates rather than permanently removes users; confirm with Gainsight support if hard deletion is required for compliance.

The most common integration failure points are auth surface confusion, SCIM prerequisites, and the inSided boundary. Developers building against the REST API sometimes attempt to reuse the SCIM Bearer token on REST endpoints (or vice versa) - both will reject the wrong token type without a clear error distinguishing the cause.

SCIM provisioning silently depends on SAML SSO being active. If SSO is later disabled or misconfigured, SCIM provisioning will break without an explicit error surfaced to the IdP admin.

Additionally, Gainsight inSided (the community platform) is a fully separate product with its own API - it shares no user management endpoints with Gainsight NXT and does not support SCIM at all, only JIT SSO. Any automation pipeline that assumes a single Gainsight API covers both products will fail for inSided users.

Custom user attributes must be pre-defined in the Gainsight admin UI before they can be set via API or SCIM; attempting to write to an undefined custom field will not create it dynamically. Finally, Google Workspace and OneLogin are not supported IdPs for SCIM - only Okta and Microsoft Entra ID are officially supported.