# SCIM provisioning

Use SCIM to add and remove Lettermint team members from an identity provider. Use it with SSO so managed users do not need to accept an invitation.

:::info
SCIM is available on paid plans. Requests for free teams are rejected.
:::


## Base URL

Use the SCIM 2.0 base URL:

```text
https://api.lettermint.co/scim/v2
```

Authenticate requests with a SCIM bearer token:

```http
Authorization: Bearer scim_your_token
```

:::warning
SCIM tokens grant access to provision and deprovision users for a team. Store them in your identity provider or secrets manager and never commit them to version control.
:::

## Create a SCIM token

SCIM tokens are created for a specific team.

1. Go to the team's SCIM token settings.
2. Click **Create token**.
3. Enter a descriptive name, such as `Okta SCIM` or `Entra ID provisioning`.
4. Optionally set an expiration date.
5. Copy the token immediately.

Lettermint only shows the token once. If the token is lost, revoke it and create a new one.


## Supported SCIM operations

Lettermint supports the SCIM Users and Groups resources for common identity provider provisioning flows.

| Operation | Endpoint | Description |
|-----------|----------|-------------|
| Service provider config | `GET /ServiceProviderConfig` | Returns supported SCIM capabilities. |
| Resource types | `GET /ResourceTypes` | Returns supported SCIM resources. |
| Schemas | `GET /Schemas` | Returns supported SCIM schemas. |
| List users | `GET /Users` | Lists users in the team. Supports `userName eq "email@example.com"` and `externalId eq "id"` filters. |
| Get user | `GET /Users/{id}` | Returns a single team user. |
| Create user | `POST /Users` | Creates or activates a team member. |
| Patch user | `PATCH /Users/{id}` | Updates the `active` state. |
| Replace user | `PUT /Users/{id}` | Replaces profile fields and applies the `active` state. |
| Delete user | `DELETE /Users/{id}` | Removes the user from the team. |
| List groups | `GET /Groups` | Lists synced SCIM groups. Supports `displayName eq "Group name"` and `externalId eq "id"` filters. |
| Get group | `GET /Groups/{id}` | Returns a single synced group. |
| Create group | `POST /Groups` | Creates a synced group and optional members. |
| Patch group | `PATCH /Groups/{id}` | Updates group fields or membership. |
| Replace group | `PUT /Groups/{id}` | Replaces group fields and membership. |
| Delete group | `DELETE /Groups/{id}` | Deletes the synced group. |

## Provision a user

Send a `POST /Users` request with the user's email address and optional name fields.

```json title="POST /Users"
{
  "externalId": "okta-user-123",
  "userName": "jane@example.com",
  "name": {
    "givenName": "Jane",
    "familyName": "Smith"
  },
  "active": true
}
```

When the request succeeds, Lettermint creates the user if needed, verifies their email address, adds them to the team as a member, and removes a matching pending invite.

New SCIM users receive the Member role with access to all current and future projects. Group role mappings can change the role after provisioning. They do not change an existing member's project access.

When your identity provider sends `externalId`, Lettermint stores it with the managed team user and returns it in future SCIM responses. This lets the identity provider reconcile users by its own immutable identifier.

## Deprovision a user

To deactivate a user, send a `PATCH /Users/{id}` request that sets `active` to `false`.

```json title="PATCH /Users/{id}"
{
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}
```

Lettermint removes the user from the team. If that team was the user's current team, Lettermint switches them to another remaining team when possible, otherwise their current team selection is cleared.

You can also send `DELETE /Users/{id}` to remove a user from the team.

:::note
If a user belongs to multiple Lettermint teams, SCIM deprovisioning only removes them from the team owned by the SCIM token. Their account and memberships in other teams remain available.
:::

## Sync groups

Lettermint accepts SCIM group push from identity providers. Groups are stored for the team and can include active team users as members.

```json title="POST /Groups"
{
  "externalId": "okta-group-123",
  "displayName": "Engineering",
  "members": [
    {
      "value": "user_id_from_scim"
    }
  ]
}
```

Group members must already be active users in the team. If your identity provider sends a group before its users, let the user provisioning job complete and retry the group sync.

## Map groups to roles

SCIM users receive the Member role by default. A member with **Manage team security** can map synced groups to reusable non-Owner roles from the SSO setup screen.

To configure a mapping:

1. Push groups from your identity provider through SCIM.
2. Open the team's SSO setup screen.
3. Find **SCIM role mapping**.
4. Choose a non-Owner role and set its priority.

When a user belongs to multiple mapped groups, the mapping with the lowest priority number wins. If two mappings have the same priority, Lettermint uses the mapping created first. Users without a matching group use the Member role.

Role synchronization changes only the member's role. Their all-project or selected-project assignment stays unchanged. Owners are never assigned, promoted, or demoted through SCIM; use the protected ownership controls in [Team members](/platform/teams/team-members) instead.


## Find users

Identity providers commonly check for existing users and groups before provisioning. Lettermint supports these filters:

- `userName eq "jane@example.com"` for users
- `externalId eq "okta-user-123"` for users
- `displayName eq "Engineering"` for groups
- `externalId eq "okta-group-123"` for groups

```http
GET /Users?filter=userName eq "jane@example.com"
```

The response uses the SCIM ListResponse format:

```json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 1,
  "Resources": []
}
```

## Identity provider setup notes

Use these settings when your identity provider asks for SCIM details:

| Setting | Value |
|---------|-------|
| SCIM version | SCIM 2.0 |
| Base URL | `https://api.lettermint.co/scim/v2` |
| Authentication | HTTP bearer token |
| Username field | Email address |
| Active field | Boolean `active` |


## Related docs

- [SSO](/platform/teams/sso)
- [Roles](/platform/teams/roles)
- [Team members](/platform/teams/team-members)