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

# Provision Users

> Automate user provisioning and deprovisioning in Essal Access using SCIM 2.0.

Essal Access supports **SCIM 2.0** for automated user lifecycle management. Connect your IdP or HR system to automatically create, update, and deactivate Essal accounts as your team changes.

## How SCIM Provisioning Works

Your upstream system (IdP, directory, or custom integration) pushes user changes to Essal's SCIM endpoint. Essal processes each change and reflects it in the Access app and across all dependent apps.

Supported SCIM operations:

* Create user (`POST /scim/v2/Users`)
* Update user attributes (`PUT` or `PATCH /scim/v2/Users/{id}`)
* Deactivate user (`PATCH` with `"active": false`)
* Delete user (`DELETE /scim/v2/Users/{id}`)
* Group membership sync (`/scim/v2/Groups`)

## Setting Up the SCIM Endpoint

### Step 1: Generate a SCIM Token

```bash theme={null}
POST /v1/access/scim/tokens
{
  "name": "Okta Provisioner",
  "description": "Used by Okta SCIM integration"
}
```

```json theme={null}
{
  "token": "scim_01HXYZSCIM_xxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-07-01T08:00:00Z"
}
```

### Step 2: Configure Your IdP

In your IdP's SCIM provisioning settings, use:

| Field             | Value                                |
| ----------------- | ------------------------------------ |
| **SCIM Base URL** | `https://access.essal.cloud/scim/v2` |
| **Auth Method**   | Bearer Token                         |
| **Token**         | The value from Step 1                |

## Provisioning a User via API

You can also provision users directly via the SCIM endpoint:

```bash theme={null}
POST https://access.essal.cloud/scim/v2/Users \
  -H "Authorization: Bearer scim_01HXYZSCIM_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane.doe@example.com",
    "name": { "givenName": "Jane", "familyName": "Doe" },
    "emails": [{ "value": "jane.doe@example.com", "primary": true }],
    "active": true
  }'
```

## Deprovisioning

When a user is removed in your IdP, SCIM sends a deactivation request. Essal sets the user's status to `suspended`, revokes all active sessions, and removes their app access within 60 seconds.

<Note>
  Suspended users are not deleted by default. Their data (documents, tasks, contacts) is preserved and can be reassigned. To permanently delete a user, use `DELETE /v1/access/users/{id}`.
</Note>

## Lifecycle Hooks

Attach webhook-based lifecycle hooks to run custom logic on provisioning events:

```bash theme={null}
POST /v1/access/lifecycle-hooks
{
  "event": "user.provisioned",
  "url": "https://hooks.example.com/new-user",
  "include_payload": true
}
```

Common use cases: auto-assign a Project workspace, send a welcome email, or create a default Sales contact record.