Copy page

Teams

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.

Base URL

Use the SCIM 2.0 base URL:

Code
https://api.lettermint.co/scim/v2

Authenticate requests with a SCIM bearer token:

Code
Authorization: Bearer scim_your_token

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.

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.

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.

Sync groups

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

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.

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

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

The response uses the SCIM ListResponse format:

Code
{
  "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

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
• Team members