> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collabase.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Users via SCIM

> How user accounts are created, updated, and deactivated automatically via the API.

<Warning>
  **Closed Beta:** The SCIM API is currently in Closed Beta and requires an Enterprise license.
</Warning>

# Managing Users via SCIM

If you need to troubleshoot your identity provider's connection, it helps to understand what happens under the hood. Here is how your provider manages users in Collabase.

## 1. View all users

When your provider checks which users are currently synchronized, it requests a list from Collabase.

**Endpoint:** `GET /api/scim/v2/Users`

Your provider can also filter this list to find specific employees (e.g., searching by email address) or load users in smaller pages if your company is very large.

## 2. Create a new user

When you assign a new employee to Collabase in your identity provider, it sends their details to this endpoint.

**Endpoint:** `POST /api/scim/v2/Users`

<Note>
  **Required field:** Only `userName` (the email address) is required. If no display name is sent, Collabase derives one from the part of the email before the `@`.
</Note>

Collabase matches incoming users in this order:

1. **By `externalId`**, if your provider sends one and a Collabase account with that `externalId` already exists.
2. **By email address (`userName`)**, if no `externalId` match was found.

If neither matches, a new account is created.

<Warning>
  If your provider sends an `externalId` that has no match, Collabase creates a new account rather than linking by email — it does not check for an existing account with the same email address first. If a local account with that email already exists (created manually, via LDAP, or another origin), the request fails instead of linking. This matters most on your first sync: make sure any pre-existing Collabase accounts your directory will provision don't collide, or let Collabase create them fresh.
</Warning>

## 3. Update a user

If a user's details change, your provider sends a `PATCH` request with one or more operations.

**Endpoint:** `PATCH /api/scim/v2/Users/{id}`

Collabase applies changes to these attributes:

| SCIM attribute                       | What it updates                                  |
| ------------------------------------ | ------------------------------------------------ |
| `active`                             | Enables or disables the account                  |
| `displayName` / `name.formatted`     | Full display name                                |
| `name.givenName` / `name.familyName` | First/last name — combined into the display name |
| `title`                              | Job title                                        |
| `externalId`                         | The provider's identifier for this user          |
| `department` (enterprise extension)  | Department                                       |

<Note>
  Both the standard `add`/`replace` operations with a `path`, and the no-path form that replaces multiple attributes in a single object, are supported.
</Note>

<Warning>
  `userName` (email) is **not** updatable via PATCH. Email changes must be made directly in Collabase — email is the matching key used to link SCIM users to accounts, so allowing it to change through the sync could silently repoint a profile at the wrong person.
</Warning>

To deactivate a user without losing their data, your provider sends a `PATCH` setting `active` to `false`. They immediately lose access to Collabase, but their documents and tasks remain safe.

## 4. Deactivate a user via DELETE

If you completely remove a user from your directory, your provider might call this endpoint instead of PATCH.

**Endpoint:** `DELETE /api/scim/v2/Users/{id}`

<Note>
  Despite the HTTP method, this does **not** permanently delete the user or their content. It has the same effect as a `PATCH` setting `active` to `false` — the account is deactivated and can be re-activated later by re-provisioning it. To permanently delete a user and their data, do it manually from **Admin → Users** in Collabase.
</Note>