This is the technical reference for wxrks's SCIM endpoint: what your identity provider (IdP) connects to, which resources, attributes and operations wxrks accepts, how roles and Organizational Units are assigned, and what happens when a user is deactivated or deleted. Use it when you set up an IdP that has no step-by-step guide, or when a sync doesn't behave as expected.
Who is this for? Account Admins and the IT administrators who configure the IdP. Generating the SCIM token and editing the SCIM settings requires Account Admin access.
SCIM (System for Cross-domain Identity Management) is the standard your IdP uses to create, update and deactivate wxrks users automatically. It is separate from wxrks Single Sign-On (SSO): SSO decides how a user signs in, and SCIM decides whether their wxrks account exists and which role it starts with.
Step-by-step IdP guides: Set Up SCIM Provisioning with Azure AD, Set up SCIM provisioning with Okta and Set up SCIM provisioning with OneLogin.
Where to find the SCIM settings
Go to Settings > Account Settings > Identity & Security, open the User Provisioning tab, and expand SCIM Provisioning.
The card's status reads Configured once a token exists, and Last user created at shows the last time SCIM created a user.
Base URL and bearer token
Value | Details |
SCIM Base URL |
|
Secret Token | Click Generate to create it. Your IdP sends it on every request as |
⚠️ Warning: The token is shown only once and can't be retrieved later. Generating a new one immediately invalidates the old one ("The existing token will be invalidated."), and every IdP still using the old token starts failing. The token has no expiry date; it stays valid until you generate a new one.
ℹ️ Note: Click Generate before you first click Save SCIM Settings on a new account. The token is what enables SCIM for the account, and requests fail with "SCIM provisioning is not enabled for this account" until a token exists.
Supported resources
Resource | Support |
Users ( | Supported: create, read, update, deactivate. |
Groups ( | Not supported. wxrks doesn't sync groups or group membership. Listing returns no groups, and every other group request fails. Turn off group provisioning in your IdP (in Okta, don't set up Push Groups; in Entra ID, disable the Provision Microsoft Entra ID Groups mapping). To give access by group, use Role Mapping: see Manage access with IdP groups below. |
| Not available. Configure your IdP manually instead of relying on schema discovery. |
Supported attributes
SCIM attribute | wxrks field | Notes |
| Username | Trimmed. |
| Only the primary email is read. An email sent without | |
| Name | Used only when both are present. |
| Name | Used only when the given and family names aren't both sent, and the user has no name yet. |
| Status |
|
| Role | Matched against Role Mapping (see below). |
| Cell phone | |
| Phone | |
| Avatar |
Every other attribute is accepted and ignored, including externalId, title, locale, timezone, preferredLanguage, addresses, groups and the enterprise extension. wxrks identifies an existing user by email, so a mapping on externalId has no effect.
Supported operations and filters
Method | Path | Behaviour |
|
| Creates the user. Returns |
|
| Lists users. Paginate with |
|
| Looks up one user by email (see filters). |
|
| Returns one user. |
|
| Updates the attributes sent; attributes you leave out are kept. Returns |
|
| Updates the attributes named in the operations. Returns |
|
| Deactivates the user (see below). Returns |
PATCH operations:
replacewith apathworks for every supported attribute, for example{"op": "replace", "path": "active", "value": false}.addandremovework for roles only, with a path such asroles[primary eq "True"].value.⚠️ A
replacewithout apath(the value is an object, such as{"op": "replace", "value": {"active": false}}) is ignored and changes nothing. Some IdPs send deactivation in exactly this form. Check how yours sends it.
Filters: only eq is supported. Whatever attribute you filter on, the value is looked up as an email, so userName eq "[email protected]" works when usernames are email addresses. The response contains zero or one user.
Errors: errors on /Users come back as wxrks JSON, not the SCIM error schema. Most validation errors return 422, for example "Email already exists", "User not found" or "Invalid SCIM Bearer Token". A wrong token returns 403. IdPs that expect 409 for a duplicate or 404 for a missing user may log these as generic failures.
Requests to /Groups, other than listing, return 501 Not Implemented in the SCIM error schema, with a message saying groups aren't supported and pointing to Role Mapping.
How role and Organizational Unit are assigned
Role. Under Role Mapping, click Add Role Mapping and pair each value your IdP sends in roles (free text, in Role in your Identity Provider) with a wxrks role: Account Admin, Project Manager, Client or Vendor. See All about wxrks Roles.
A
rolesvalue with no matching row is ignored.A user created without any
rolesvalue gets no role, and can't do anything until you assign one in People > Users.Role changes in the IdP sync to wxrks: a role added in the IdP is added in wxrks, and a role removed in the IdP is removed in wxrks.
Organizational Unit. Every user created through SCIM is placed in the Default Organizational Unit selected on the card. SCIM has no attribute for choosing a different unit, and updates never move a user. Move users between units in wxrks.
Click Save SCIM Settings after changing the role mapping or the default unit.
Manage access with IdP groups
wxrks reads access from each user's roles attribute, not from groups. To manage access with IdP groups, have each group send a roles value for its members, and map that value to a wxrks role.
In your IdP, assign the group to the wxrks app and give its members a
rolesvalue, for examplewxrks-vendor. In Entra ID, create an app role with that value, assign the group to the app with that role, and mapAppRoleAssignmentsComplex([appRoleAssignments])toroles. In Okta, add arolesattribute to the app's user profile and set its value on the group assignment.In wxrks, under Role Mapping, click Add Role Mapping, enter the same value in Role in your Identity Provider, choose the wxrks role, and click Save SCIM Settings.
Users provisioned from the group get the mapped role when they're created, and members added to the group later get it on the next sync.
Use one value per wxrks role, and map every value your groups send: a value with no matching row is ignored, and a user created without a mapped role can't do anything until you assign one in People > Users.
When a user leaves a group, the role that group gave them is removed in wxrks on the next sync. If they leave every group assigned to the wxrks app, your IdP unassigns them and they're deactivated (see Deactivation and deletion).
Deactivation and deletion
active: false (via PUT or PATCH) and DELETE do the same thing: the user's status becomes deactivated. Nothing is erased.
What | Effect of deactivation |
Sign-in | Blocked immediately. |
Sessions already open | Keep working for up to about 5 minutes, then stop. |
API keys | Not deleted. After deactivation, exchanging the user's API ID and API Secret Key for a token fails. A token issued before deactivation keeps working for up to about 5 minutes, then stops. |
Open and assigned tasks | Unchanged. They stay assigned to the deactivated user. Reassign them from the project's Tasks tab. |
The user record, history and authorship | Kept. |
Sending active: true reactivates the user.
💡 Tip: Before you unassign a linguist or PM in the IdP, reassign their open tasks in wxrks, or ask a PM to. SCIM won't do it for you.
Quick reference
Item | Value |
Base URL |
|
Auth |
|
Resources | Users only |
Match key | Primary email |
Filter |
|
Pagination |
|
DELETE | Deactivates, never erases |
Groups | Not supported. Give access by group through Role Mapping |
Schema discovery | Not supported |

