Skip to main content

​
Overview

TextQL supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user and group provisioning. When connected to your identity provider, SCIM keeps your TextQL organization in sync. Users and groups are automatically created, updated, and deactivated as changes happen in your IdP.

​
Supported Identity Providers

Any identity provider that supports the SCIM 2.0 protocol can be used, including:
  • Okta
  • Microsoft Entra ID (Azure AD)
  • OneLogin
  • Ping Identity

​
Prerequisites

Before configuring SCIM, ensure:
  1. You have admin access to your TextQL organization
  2. You have admin access to your identity provider

​
Setting Up SCIM

​
Step 1: Generate a SCIM Token

From the left sidebar, click Settings. In the Configuration tab, scroll to the SCIM Provisioning section and click Create Token. Give your token a description (e.g., “Okta SCIM”) so you can identify it later.
Copy your SCIM token immediately after creation. For security reasons, you won’t be able to see the full token again.

​
Step 2: Configure Your Identity Provider

In your identity provider, create a new SCIM application or add SCIM provisioning to your existing application. You’ll need:
  • SCIM Base URL: https://app.textql.com/scim/v2 (for VPC or custom deployments, use your own TextQL host)
  • Authentication: Bearer token (paste the token from Step 1)

​
Step 3: Enable Provisioning

In your identity provider, enable the provisioning features you want:
FeatureDescription
Create UsersNew users assigned in your IdP are automatically added to TextQL
Update User AttributesName and email changes sync to TextQL
Deactivate UsersRemoving a user in your IdP deactivates them in TextQL
Push GroupsGroups and their memberships are synced to TextQL roles

​
Step 4: Assign Users and Groups

In your identity provider, assign users and groups to the TextQL application. Your IdP will begin syncing them automatically.

​
How It Works

​
User Provisioning

When your IdP pushes a user to TextQL via SCIM:
  1. TextQL checks if the user’s email already exists
  2. If the user exists, a SCIM mapping is created linking the IdP’s external ID to the existing account
  3. If the user doesn’t exist, a new identity and organization membership are created
  4. The user can immediately log in
When a user is deactivated in your IdP:
  1. The IdP sends a SCIM deactivation request
  2. TextQL marks the user as inactive
  3. The user can no longer access the organization
  4. Their data and history are preserved (not deleted)

​
Group Provisioning

SCIM groups map to TextQL roles. When your IdP pushes a group:
  1. A new role is created in TextQL with the group’s display name
  2. Members of the group are assigned to that role
  3. Adding or removing members in your IdP automatically updates role assignments
  4. Deleting a group in your IdP removes the corresponding role
When updating group membership, TextQL accepts both object-form and path-based PATCH operations. Okta’s group push feature uses path-based syntax ("path": "members") for replace operations, which is fully supported.
If a group push operation contains a malformed members payload, TextQL returns a 400 Bad Request immediately rather than silently ignoring the bad data.

​
Managing SCIM Tokens

You can create multiple SCIM tokens if needed (e.g., one per IdP environment). To revoke a token, go to Settings > SCIM Provisioning and click Revoke next to the token. Revoking a token immediately stops all provisioning from any IdP using that token. Existing users and groups are not affected; they remain in their current state.

​
Troubleshooting

​
Users not being provisioned

  • Verify the SCIM token is active (not revoked or expired)
  • Check that users are assigned to the TextQL application in your IdP
  • Ensure the SCIM Base URL is correct

​
Groups not syncing

  • Confirm group push is enabled in your IdP’s provisioning settings
  • Verify the groups are assigned to the TextQL application
  • Check that group members also have individual user assignments

​
”A role with this name is already linked to a SCIM group” (409 Conflict)

  • This error occurs when your IdP tries to push a group whose display name matches a TextQL role that is already managed by a different SCIM mapping.
  • To resolve: either rename the group in your IdP, or delete the existing SCIM mapping for that role before re-pushing.

​
User deactivation not working

  • Ensure your IdP is sending a SCIM PATCH with active: false (most IdPs do this by default)
  • Verify the SCIM token has not been revoked

​
”Error authenticating: Unauthorized” (Okta)

  • When configuring SCIM in Okta, the API Token field requires the token prefixed with Bearer . For example: Bearer <your-token>
  • Pasting only the raw token without the Bearer prefix will result in an authentication error

​
Changes not appearing immediately

  • Most IdPs sync on a schedule (typically every 30-60 minutes)
  • Use your IdP’s “Push Now” or “Force Sync” option to trigger an immediate sync

​
Security Considerations

  • SCIM tokens are stored as hashed values. TextQL cannot retrieve the original token after creation.
  • All SCIM endpoints require a valid bearer token.
  • SCIM operations are scoped to the organization that owns the token.
  • Only organization administrators can create or revoke SCIM tokens.
  • User deactivation via SCIM is a soft delete. Accounts can be reactivated if the user is re-assigned in your IdP.