# Provision users with SCIM

Connect your identity provider's SCIM 2.0 client to Tracix to create, update and deactivate users and push groups, using a bearer token you can rotate.

SCIM 2.0 lets your identity provider (IdP) create, update and deactivate Tracix accounts for you, so people join and leave Tracix when they join and leave your company. SCIM works alongside [single sign-on](https://tracix.io/docs/admin/sso): the people it provisions sign in through your IdP.

## Before you begin

* You need the Owner, Admin or MSP admin role.
* Set up [single sign-on](https://tracix.io/docs/admin/sso) first, with your domain verified. Provisioned people sign in with SSO, and SSO links each sign-in to the provisioned account.

## Connect your identity provider

**1. Create a SCIM token**

In the console, open **Security**. In the **Enterprise SSO** section, under **SCIM provisioning**, select **Rotate SCIM token**. Copy the token from **New SCIM token — save it now**: it starts with `scim_` and is shown only once.

**2. Configure your IdP's SCIM app**

In your IdP's provisioning settings for the Tracix app, enter the base URL and the token:

| Setting        | Value                                      |
| -------------- | ------------------------------------------ |
| SCIM base URL  | `https://cloud.tracix.io/api/auth/scim/v2` |
| Authentication | HTTP bearer token: the `scim_` token       |

**3. Map externalId to the user's SSO subject**

Set the SCIM `externalId` attribute to the same immutable value your SSO sends: the OIDC subject (`sub`) or the signed SAML NameID. Don't map it to an email address or username. Tracix uses it to match each SSO sign-in to the provisioned account.

**4. Assign people**

Assign people, and groups if you push them, to the Tracix app in your IdP. Your IdP creates their accounts in your organization.

## What SCIM does in Tracix

| Your IdP does this                   | Tracix does this                                                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Creates a user                       | Creates an account in your organization with the Member role. The email address can't already belong to a Tracix account. |
| Updates a user                       | Updates the account's profile.                                                                                            |
| Deactivates a user (`active: false`) | Blocks sign-in, ends the person's sessions and removes their access to every workspace.                                   |
| Reactivates a user (`active: true`)  | Allows sign-in again. Add the person back to workspaces on their **Access** tabs.                                         |
| Pushes groups                        | Stores the groups and their members. Groups don't grant roles in Tracix.                                                  |

At each SSO sign-in, the person's organization role comes from the **Default role** and **Group-to-role mappings** in your SSO settings; see [Map identity provider groups to roles](https://tracix.io/docs/admin/sso#map-identity-provider-groups-to-roles). Workspace access isn't provisioned through SCIM: grant it on each workspace's **Access** tab.

## Endpoints

All paths are relative to the base URL, `https://cloud.tracix.io/api/auth/scim/v2`, and every request carries `Authorization: Bearer <SCIM token>`.

| Path                         | Use                                                      |
| ---------------------------- | -------------------------------------------------------- |
| `/Users`, `/Users/{id}`      | Create, read, update and deactivate users                |
| `/Groups`, `/Groups/{id}`    | Create, read, update and delete groups and their members |
| `/ServiceProviderConfig`     | What the SCIM server supports                            |
| `/Schemas`, `/ResourceTypes` | The user and group schemas                               |

## Rotate the token

Select **Rotate SCIM token** again to create a new token. The previous token stops working immediately, so paste the new one into your IdP right away.

## Next steps

- [Single sign-on](https://tracix.io/docs/admin/sso): Group mappings and required SSO

- [Users and roles](https://tracix.io/docs/admin/users-and-roles): Organization and workspace roles

- [Invite your team](https://tracix.io/docs/get-started/invite-your-team): Grant workspace access