Documentation Index
Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
Use this file to discover all available pages before exploring further.
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:
https://app.langwatch.ai/api/scim/v2
https://your-langwatch-instance.example.com/api/scim/v2
Step 2: Generate a Bearer Token
- In Settings → SCIM, click Generate Token
- Optionally add a description (e.g.,
Okta SCIM integration)
- Click Generate Token
- 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.
| Setting | Value |
|---|
| SCIM Base URL | https://app.langwatch.ai/api/scim/v2 |
| Bearer Token | Your generated token |
Supported Operations
LangWatch SCIM 2.0 supports the following user operations:
| Operation | Description |
|---|
| Create User | Provisions a new user and adds them to your organization as a Member |
| Get User | Retrieves a single user by ID |
| List Users | Lists all users in the organization, with optional userName filtering |
| Update User (PUT) | Replaces user attributes (name, email, active status) |
| Update User (PATCH) | Partially updates user attributes (e.g., deactivate only) |
| Delete User | Deactivates the user (soft delete — their data is preserved) |
SCIM Endpoints
| Endpoint | Methods |
|---|
/api/scim/v2/Users | GET, POST |
/api/scim/v2/Users/{id} | GET, PUT, PATCH, DELETE |
/api/scim/v2/Groups | GET, POST |
/api/scim/v2/Groups/{id} | GET, PUT, PATCH, DELETE |
/api/scim/v2/ServiceProviderConfig | GET |
/api/scim/v2/ResourceTypes | GET |
/api/scim/v2/Schemas | GET |
User Attributes
| SCIM Attribute | LangWatch Field | Notes |
|---|
userName | Email address | Used as the unique identifier |
name.givenName | First name | Combined into display name |
name.familyName | Last name | Combined into display name |
emails[primary] | Email address | Should match userName |
active | Account status | false deactivates the user |
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:
| Column | Description |
|---|
| Description | Optional label you provided when creating the token |
| Created | Date the token was generated |
| Last Used | Date the token was last used to authenticate a SCIM request |
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.
