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.

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

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

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

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

Related docs

• SSO
• Roles
• Team members