> ## Documentation Index
> Fetch the complete documentation index at: https://collabase.ch/docs/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.
</Warning>

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>