# Provision people from your identity provider or HR system

> Let your identity provider or HR system add, update and remove people in Trustaige over SCIM 2.0, with the endpoint and token the hub gives you.

Source: https://docs.trustaige.com/manage/scim-provisioning

Replace these placeholders with your organization's own values:

- `<your-org-uuid>`: Organization ID, for example `7c0e3f52-9d1a-4b8e-a6f4-2b1d9c3e5a70`. The UUID after /provision/ in the SCIM endpoint the hub shows when you connect a source.
- `<your-scim-token>`: SCIM token, a secret. The hub shows it once, when you create the token.

Your identity provider or HR system can be the place people are added to and
removed from Trustaige. It pushes every change over SCIM 2.0, the standard most
of them already speak: nobody types a new hire in twice, and someone who leaves
loses access here the moment that system says so.

The hub gives you two things to paste into the other system: your
organization's **SCIM endpoint** and a **Bearer token**. This page explains
both, and what Trustaige does with what it receives.

1. Your IdP or HR system → Trustaige: create, update, deactivate users; push groups (SCIM 2.0, bearer token)
2. Trustaige → Your IdP or HR system: the user or group as Trustaige stored it

## Before you begin

| You need | Why |
|---|---|
| The **Manage provisioning** permission, or superadmin | The **Provisioning** page needs it. Creating a token also asks you to confirm it's you. |
| Your primary domain **proved by DNS** | A system that writes to your directory needs more than the mailbox your organization was created with. See [Domains](/manage/domains). |
| A system that pushes **SCIM 2.0** | Usually your identity provider; many HR systems do too. |
| Free seats | Every active person a source creates takes a seat. |

## 1. Create the credentials

1. Open **Directory → Provisioning** and click **Connect a source**.
2. Under **Which system is this?**, name the system that will push people
   here. The name appears only in your list of sources.
3. Click **Create the credentials**.
4. Copy the **SCIM endpoint** and the **Bearer token**, then click **I have
   copied both**.

The token is shown once. Trustaige doesn't keep it in a readable form, so once
you leave the page nobody can show it again. If it's ever lost, revoke it and
connect again.

The **SCIM endpoint** is the same for every source in your organization:

```txt title="SCIM endpoint"
https://id.trustaige.com/provision/<your-org-uuid>/scim/v2
```

> **Note:** If a service provider set this up for you, the token is created only when one
> of your superadmins activates the request. It's shown to that superadmin, who
> hands it to whoever configures the source. Until then, the source shows **Off
> until activated**.

## 2. Paste them into the other system

In your identity provider or HR system, open its SCIM or user provisioning
settings. The names differ from one system to the next; these are the settings
every one of them asks for:

| Setting | Also called | Value |
|---|---|---|
| **Base URL** | Tenant URL, SCIM connector base URL | `https://id.trustaige.com/provision/<your-org-uuid>/scim/v2` |
| **Authentication** | Bearer token, HTTP header, secret token | Bearer, with the token from step 1: `<your-scim-token>` |
| **User identifier** | Unique identifier field, matching attribute | `userName` |
| **Actions** | Provisioning to app | Create, update and deactivate users; push groups |
| **Test connection** | Verify, test credentials | Press it |

The hub waits on **Waiting for … to make its first request** and moves on by
itself as soon as the system calls Trustaige with the token. You can also click
**Finish later** or **Skip the check**.

### Check it from a terminal

To check the endpoint and token without the other system, ask Trustaige what
it supports. A working token returns the configuration below; this request also
counts as the source's first request.

```bash title="Test the token"
curl https://id.trustaige.com/provision/<your-org-uuid>/scim/v2/ServiceProviderConfig \
  -H "Authorization: Bearer <your-scim-token>"
```

```json title="Response"
{
  "authenticationSchemes": [
    {
      "description": "Authentication scheme using the OAuth Bearer Token Standard",
      "name": "OAuth Bearer Token",
      "type": "oauthbearertoken"
    }
  ],
  "bulk": { "maxOperations": 0, "maxPayloadSize": 0, "supported": false },
  "changePassword": { "supported": false },
  "documentationUri": "https://tools.ietf.org/html/rfc7644",
  "etag": { "supported": false },
  "filter": { "maxResults": 200, "supported": true },
  "patch": { "supported": true },
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "sort": { "supported": false }
}
```

## What Trustaige does with what it receives

| The source sends | Trustaige |
|---|---|
| A new user | Adds the person to your directory as a member, using their email: the one marked primary, or the only one sent, or otherwise `userName`, which must then be an email address. |
| `active: false`, by PUT or PATCH | Suspends their membership. `active: true` restores it. |
| DELETE on a user | Revokes their membership and signs them out of your organization. They need a new invitation to come back. |
| A group, and its members | Creates or updates the group in your directory. A group named in a policy's scope can't be deleted from the source; remove it from the policy first. |

People a source creates appear under **Directory → Users**. Trustaige doesn't
email them when a source creates them: open the person, go to **Security**, and
under **Device Registration** click **Create Link** to give them a link to set
up their passkey.

What Trustaige accepts, for whoever configures the source:

| | |
|---|---|
| User attributes | `userName` (required), `externalId`, `active`, `name`, `displayName`, `nickName`, `profileUrl`, `title`, `userType`, `preferredLanguage`, `locale`, `timezone`, `emails`, `phoneNumbers`, `addresses` |
| Enterprise extension | `employeeNumber`, `costCenter`, `organization`, `division`, `department`, `manager` |
| Filters | `eq` only. Users: `userName`, `externalId`, `emails.value`. Groups: `displayName`, `externalId`. |
| PATCH | Supported, for users and groups |
| Bulk, sort, ETags | Not supported |

## Manage your sources

**Directory → Provisioning** lists every source under **Into your directory**:
**Waiting for first push** until it has called, then **Pushing**, with the time
since its last push.

To disconnect a source, click **Revoke** on it. Its next push is refused, so
people it adds, changes or removes stop reaching your directory. People it
already created stay. A revoked token can't be restored; to connect the source
again, create new credentials and paste the new token into its settings.

## Troubleshooting

**“An HR system cannot provision people until … is proven by DNS.”**

Your primary domain was proved only by email. Prove it by DNS on
[Domains](/manage/domains), then create the credentials.

**The source reports “Invalid or revoked token”**

The token was mistyped, or has been revoked. Paste it again; if it's lost,
revoke it and create new credentials.

**The source reports “Token does not belong to this tenant”**

The endpoint and the token are from different organizations. Copy both again
from the same **Connect a source** run.

**The source reports “no seats available: … in use — purchase additional seats”**

Your organization has no free seats for the person being created. Add seats,
or free some, and let the source retry.

**The source reports “user already exists (email or username conflict)”**

Someone in your directory already has that email address or `userName`. Map
the source's matching attribute to `userName` so it finds the existing person
instead of creating them again.

**The source reports “unsupported filter …”**

Trustaige matches users on `userName`, `externalId` or `emails.value`, and
groups on `displayName` or `externalId`, with `eq`. Set the source's matching
attribute to one of those.

**The source reports “group is referenced by policy scopes and cannot be deleted”**

A policy in Trustaige applies to that group. Remove the group from the
policy's scope, then let the source delete it.

**The wizard stays on Waiting for … to make its first request**

The source hasn't called Trustaige with this token yet. Press its test or
provision button, or run the terminal check above.