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 guide: Set Up SCIM Provisioning with Azure AD.

Where to find the SCIM settings

Go to Settings > Account Settings > Identity & Security, open the User Provisioning tab, and expand SCIM Provisioning.

Identity & Security > User Provisioning tab with a red box around the expanded SCIM Provisioning card: SCIM Base URL with its copy button, Secret Token with the Generate button, Role Mapping with Add Role Mapping, Default Organizational Unit, and Save SCIM Settings.

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	`https://<your wxrks domain>/scim/v2/<account ID>`. It is unique to your account; use the copy button next to it. Your IdP appends `/Users` or `/Groups`.
Secret Token	Click Generate to create it. Your IdP sends it on every request as `Authorization: Bearer <token>`. The header must start with `Bearer`, followed by a space.

⚠️ 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 (`/Users`)	Supported: create, read, update, deactivate.
Groups (`/Groups`)	Not supported. Listing returns no groups, and creating a group fails. Turn off group push in your IdP and assign access per user, or through IdP groups that assign users to the app.
`ServiceProviderConfig`, `Schemas`, `ResourceTypes`	Not available. Configure your IdP manually instead of relying on schema discovery.

Supported attributes

SCIM attribute	wxrks field	Notes
`userName`	Username	Trimmed.
`emails` (entry with `"primary": true`)	Email	Only the primary email is read. An email sent without `"primary": true` is ignored. The email must not already exist in wxrks.
`name.givenName` + `name.familyName`	Name	Used only when both are present.
`displayName`	Name	Used only when the given and family names aren't both sent, and the user has no name yet.
`active`	Status	`true` → active; `false` → deactivated.
`roles`	Role	Matched against Role Mapping (see below).
`phoneNumbers` (`type: mobile`)	Cell phone
`phoneNumbers` (`type: work`)	Phone
`photos` (`type: thumbnail`)	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
`POST`	`/Users`	Creates the user. Returns `201`.
`GET`	`/Users`	Lists users. Paginate with `startIndex` and `itemsPerPage` (default 200).
`GET`	`/Users?filter=…`	Looks up one user by email (see filters).
`GET`	`/Users/{id}`	Returns one user. `{id}` is the wxrks user ID returned on create.
`PUT`	`/Users/{id}`	Updates the attributes sent; attributes you leave out are kept. Returns `200`.
`PATCH`	`/Users/{id}`	Updates the attributes named in the operations. Returns `200`.
`DELETE`	`/Users/{id}`	Deactivates the user (see below). Returns `204`.

PATCH operations:

replace with a path works for every supported attribute, for example {"op": "replace", "path": "active", "value": false}.
add and remove work for roles only, with a path such as roles[primary eq "True"].value.
⚠️ A replace without a path (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 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.

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 roles value with no matching row is ignored.
A user created without any roles value gets no role, and can't do anything until you assign one in People > Users.
⚠️ Removing or changing a role in the IdP doesn't remove it in wxrks. Role changes only ever add roles. To take a role away, edit the user in People > Users.

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.

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	`https://<your wxrks domain>/scim/v2/<account ID>`
Auth	`Authorization: Bearer <Secret Token>`
Resources	Users only
Match key	Primary email
Filter	`eq` on email
Pagination	`startIndex`, `itemsPerPage`
DELETE	Deactivates, never erases
Groups, schema discovery	Not supported

SCIM user provisioning reference