Skip to main content
SCIM (System for Cross-domain Identity Management) 2.0 allows your identity provider to automatically manage user lifecycle in LangWatch, provisioning new users when they join your organization and deprovisioning them when they leave, without any manual intervention.

​
Prerequisites

  • Organization Admin permissions in LangWatch
  • An identity provider that supports SCIM 2.0 (Okta, Azure AD, Entra ID, etc.)
  • SSO configured for your organization (recommended, see SSO Setup)

​
Setting Up SCIM

​
Step 1: Get Your SCIM Base URL

Navigate to Settings → SCIM in your LangWatch organization. The SCIM Base URL is displayed at the top of the page:
For self-hosted deployments, replace the domain with your own:

​
Step 2: Generate a Bearer Token

  1. In Settings → SCIM, click Generate Token
  2. Optionally add a description (e.g., Okta SCIM integration)
  3. Click Generate Token
  4. Copy the token immediately: it will not be shown again
Store your SCIM bearer token securely. Once you close the dialog, the token value cannot be retrieved. If you lose the token, revoke it and generate a new one.
You can generate multiple tokens (e.g., one per integration) and revoke them individually from the token table.

​
Step 3: Configure Your Identity Provider

Use the SCIM Base URL and bearer token to configure SCIM in your identity provider: Refer to your identity provider’s own documentation for where to enter these values:

​
Supported Operations

LangWatch SCIM 2.0 supports the following user operations:

​
SCIM Endpoints

​
User Attributes

​
User Lifecycle Behavior

​
Provisioning (Create)

When your identity provider provisions a user:
  • If the user does not exist in LangWatch, a new account is created and added to your organization
  • If the user already exists (same email) but is not in your organization, they are added as a Member
  • If the user already exists and is deactivated, their account is reactivated
New users provisioned via SCIM are assigned the Member role by default. You can adjust roles manually in LangWatch after provisioning using RBAC, or use SCIM Groups to automatically assign roles based on group membership.

​
Deprovisioning (Delete/Deactivate)

When your identity provider sends a DELETE for a user:
  • Their org membership and all role bindings are removed
  • Their account is deactivated: they can no longer sign in
  • Their data (traces, annotations, datasets) is preserved
  • A second DELETE returns 404 Not Found, the operation is idempotent
When your identity provider suspends a user (PATCH active: false):
  • Their account is deactivated: they can no longer sign in
  • Their org membership and role bindings are preserved
  • Re-activating (active: true) immediately restores access
Use active: false for temporary suspension and DELETE for permanent offboarding. DELETE removes all memberships and role bindings, re-provisioning the user starts from scratch.

​
Managing Tokens

From Settings → SCIM, you can manage all bearer tokens: To revoke a token, click the delete icon next to it and confirm. Any identity provider using that token will immediately lose access.

​
Security Considerations

  • Rotate tokens regularly: generate a new token and update your IdP before revoking the old one to avoid downtime
  • One token per integration: use separate tokens for each identity provider or environment so you can revoke them independently
  • Combine with SSO: SCIM works best when paired with SSO so that provisioned users sign in via your IdP rather than email/password
  • Audit token usage: the “Last Used” column helps identify unused or stale tokens

​
Troubleshooting

Test connection fails in my identity provider
  • Verify the SCIM Base URL ends with /api/scim/v2 (no trailing slash)
  • Ensure the bearer token is pasted correctly without extra whitespace
  • Confirm the token has not been revoked in LangWatch
Users are not being provisioned
  • Check that users or groups are assigned to the application in your IdP
  • Verify that Create Users is enabled in your IdP’s provisioning settings
  • Review provisioning logs in your IdP for detailed error messages
Deactivated users can still sign in
  • SCIM deactivation prevents future sign-ins but active sessions may persist until they expire
  • For immediate access removal, also revoke the user’s active sessions from your IdP
User shows “already exists” error
  • A user with the same email may already be a member of the organization, this is expected behavior and can be safely ignored
For additional help, contact us at support@langwatch.ai.