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

# SCIM provisioning

> Automate user and group lifecycle management with SCIM 2.0.

Truthlocks supports SCIM 2.0 for automated user provisioning and group management. Connect your identity provider (Okta, Azure AD, OneLogin, etc.) to automatically create, update, and deactivate users in your Truthlocks tenant.

<Info>
  SCIM provisioning is available on the **Business** plan and above.
</Info>

## How it works

<Steps>
  <Step title="Generate a SCIM token">
    In the console, go to **Settings > SCIM** and generate a bearer token.
    This token authenticates your IdP's SCIM requests.
  </Step>

  <Step title="Configure your IdP">
    In your identity provider, set the SCIM base URL to
    `https://api.truthlocks.com/scim/v2` and paste the bearer token.
  </Step>

  <Step title="Sync users and groups">
    Your IdP pushes user creates, updates, and deactivations to Truthlocks
    automatically. Group membership changes update role assignments.
  </Step>
</Steps>

## SCIM base URL

```text theme={null}
https://api.truthlocks.com/scim/v2
```

All SCIM requests must include the bearer token in the `Authorization` header:

```bash theme={null}
curl -X GET https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here"
```

## Supported operations

### Users

| Operation | Method | Path                  | Description                       |
| --------- | ------ | --------------------- | --------------------------------- |
| List      | GET    | `/scim/v2/Users`      | List users with optional filter   |
| Create    | POST   | `/scim/v2/Users`      | Provision a new user              |
| Get       | GET    | `/scim/v2/Users/{id}` | Retrieve a user by SCIM ID        |
| Replace   | PUT    | `/scim/v2/Users/{id}` | Full user replacement             |
| Patch     | PATCH  | `/scim/v2/Users/{id}` | Partial update (e.g., deactivate) |
| Delete    | DELETE | `/scim/v2/Users/{id}` | Suspend the user                  |

### Groups

| Operation | Method | Path                   | Description                           |
| --------- | ------ | ---------------------- | ------------------------------------- |
| List      | GET    | `/scim/v2/Groups`      | List groups                           |
| Create    | POST   | `/scim/v2/Groups`      | Create a group mapping                |
| Get       | GET    | `/scim/v2/Groups/{id}` | Retrieve a group by SCIM ID           |
| Replace   | PUT    | `/scim/v2/Groups/{id}` | Replace group (re-maps role bindings) |
| Patch     | PATCH  | `/scim/v2/Groups/{id}` | Add or remove members                 |
| Delete    | DELETE | `/scim/v2/Groups/{id}` | Delete group mapping                  |

### Discovery

| Method | Path                             | Description              |
| ------ | -------------------------------- | ------------------------ |
| GET    | `/scim/v2/ServiceProviderConfig` | Supported capabilities   |
| GET    | `/scim/v2/Schemas`               | Resource schemas         |
| GET    | `/scim/v2/ResourceTypes`         | Available resource types |

## Creating a user

```bash theme={null}
curl -X POST https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@example.com",
    "name": { "givenName": "Jane", "familyName": "Smith" },
    "emails": [{ "value": "jane@example.com", "primary": true }],
    "active": true
  }'
```

## Deactivating a user

IdPs like Okta and Azure AD send a PATCH request to deactivate users:

```bash theme={null}
curl -X PATCH https://api.truthlocks.com/scim/v2/Users/{id} \
  -H "Authorization: Bearer scim_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{ "op": "replace", "path": "active", "value": false }]
  }'
```

Deactivated users lose access immediately but their data is retained.

## Managing SCIM tokens

Generate and manage tokens through the management API:

```bash theme={null}
# Generate a new token
curl -X POST https://api.truthlocks.com/v1/scim/tokens \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Okta SCIM" }'

# List tokens
curl -X GET https://api.truthlocks.com/v1/scim/tokens \
  -H "Authorization: Bearer <admin_token>"

# Revoke a token
curl -X DELETE https://api.truthlocks.com/v1/scim/tokens/<token_id> \
  -H "Authorization: Bearer <admin_token>"
```

## Activity log

All SCIM operations are recorded in an activity log. View recent provisioning events:

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/scim/activity \
  -H "Authorization: Bearer <admin_token>"
```

Activity types include `USER_CREATED`, `USER_DEACTIVATED`, `USER_PATCHED`, `GROUP_CREATED`, `GROUP_UPDATED`, and `GROUP_DELETED`.

## Seat enforcement

User creation respects your plan's seat limit. If the limit would be exceeded, the SCIM endpoint returns HTTP `402` and the user is not created. Upgrade your plan or remove inactive users to free seats.

## Filtering

The SCIM `filter` query parameter lets your identity provider narrow list responses to specific users or groups. Truthlocks supports filtering on specific SCIM attributes using the operators below.

### Supported filter attributes

| Attribute     | Resource      | Description                                              |
| ------------- | ------------- | -------------------------------------------------------- |
| `userName`    | Users         | The user's login identifier (usually an email address)   |
| `displayName` | Users, Groups | The user's or group's display name                       |
| `externalId`  | Users, Groups | The unique identifier assigned by your identity provider |
| `active`      | Users         | Whether the user account is active (`true` / `false`)    |

### Supported operators

| Operator | Meaning     | Example                          |
| -------- | ----------- | -------------------------------- |
| `eq`     | Equals      | `userName eq "jane@example.com"` |
| `ne`     | Not equals  | `active ne false`                |
| `co`     | Contains    | `userName co "example.com"`      |
| `sw`     | Starts with | `userName sw "jane"`             |
| `ew`     | Ends with   | `userName ew "@example.com"`     |

Combine operators using `and` / `or` for complex queries:

```bash theme={null}
# Find active users whose username contains "example.com"
curl -G https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  --data-urlencode 'filter=active eq true and userName co "example.com"'

# Find users starting with "jane" or "john"
curl -G https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  --data-urlencode 'filter=userName sw "jane" or userName sw "john"'

# Look up a user by their IdP-assigned external ID
curl -G https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  --data-urlencode 'filter=externalId eq "00u1a2b3c4d5e6f7g8h9"'

# Find a user by display name
curl -G https://api.truthlocks.com/scim/v2/Users \
  -H "Authorization: Bearer scim_your_token_here" \
  --data-urlencode 'filter=displayName eq "Jane Smith"'
```

<Note>
  Filtered results are capped at 200 items per response. If your IdP syncs more than 200 users or groups, it should paginate using the `startIndex` and `count` parameters alongside the filter.
</Note>

### Common IdP filter patterns

Most identity providers send filters automatically during sync. Here are the patterns that Truthlocks handles:

| IdP      | Typical filter sent                                                                 |
| -------- | ----------------------------------------------------------------------------------- |
| Okta     | `userName eq "user@example.com"`                                                    |
| Azure AD | `userName eq "user@example.com"`, `displayName co "Smith"`, or `externalId eq "id"` |
| OneLogin | `userName sw "user"` or `externalId eq "id"`                                        |

If your IdP sends a filter using any of the supported attributes and operators listed above, Truthlocks processes it correctly. You do not need to configure anything on the Truthlocks side.

## Supported capabilities

| Capability      | Supported                                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Patch           | Yes                                                                                                                         |
| Bulk            | No                                                                                                                          |
| Filter          | Yes — `eq`, `ne`, `co`, `sw`, `ew` on `userName`, `displayName`, `externalId`, `active` with `and` / `or` (max 200 results) |
| Sort            | No                                                                                                                          |
| Change password | No                                                                                                                          |
| ETag            | No                                                                                                                          |

## Related

* [SAML SSO](/security/saml-sso) — Authenticate users through your IdP.
* [RBAC & permissions](/security/rbac) — Roles assigned to provisioned users.
* [Audit logs](/security/audit) — Track all access and provisioning events.