# SCIM

SCIM lets your identity provider automatically add and remove Lettermint team members. It is designed to work with SSO so managed users can access the right team without accepting an invitation.

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

{/* Screenshot placeholder: /docs/images/sso/admin-scim-token-list.png */}

## 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.

{/* Screenshot placeholder: /docs/images/sso/admin-create-scim-token.png */}

## 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.

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 are added as `member` by default. Team owners can map synced SCIM groups to Lettermint roles from the SSO setup screen.

Use this for administrator access:

1. Push groups from your identity provider through SCIM.
2. Open the team's SSO setup screen.
3. Find **SCIM role mapping**.
4. Set the administrator group to `Owner`.

Users in a mapped owner group become owners. SCIM-managed users that are not in an owner group stay or become members. Lettermint will not demote the final remaining owner, even if the identity provider removes that user from the owner group.

{/* Screenshot placeholder: /docs/images/sso/admin-scim-role-mapping.png */}

## 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` |

{/* Screenshot placeholder: /docs/images/sso/idp-scim-settings.png */}

## Audit history

Lettermint records durable team security events for SCIM token creation and revocation, user provisioning and deprovisioning, and group create, update, and delete operations. Team members can review recent SCIM events in the dashboard.

## Related docs

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