SCIM 2.0 Integration Documentation

Overview

Our SCIM2.0 implementation allows you to automatically provision and manage users and teams from your identity provider to our platform. This integration supports creating, updating, reading, and deactivating users and teams.

SCIM must be set up in a separate app from your SSO setup. Create a dedicated SCIM 2.0 OAuth bearer token app to avoid conflicts.

Getting Started

Authentication

All SCIM requests require a Bearer token in the Authorization header:

Authorization: Bearer your-scim-token

Bearer tokens can be generated in the "SCIM" tab under the "Connect" settings tab.

Base URL

All SCIM endpoints are available at:

https://api.latchapp.com/scim/v2

Supported Features

• User operations - Create, disable, and manage users

• GROUP operations - Create, delete, and manage teams

Not Supported

• User deletion

• Bulk operations

• Password management

API Endpoints

Discovery Endpoints

Service Provider Configuration

GET /v2/ServiceProviderConfig

Returns supported SCIM features and capabilities.

Resource Types

GET /v2/ResourceTypes

Lists available resource types (User, Group).

Schemas

GET /v2/Schemas

Returns supported SCIM schemas and extensions.

User Management

List Users

GET /v2/Users

Get User

GET /v2/Users/{id}

Create User

POST /v2/Users

Update User

PUT /v2/Users/{id}    # Merges updates with existing user
PATCH /v2/Users/{id}  # Partial updates to existing user

Deactivate User

Users are deactivated (not deleted) by setting active: false in an update operation.

User Attribute Mapping

Core Attributes:

Email Mapping

We automatically extract emails from various SCIM name formats:

• email

• emails: [ { primary: true, value: email }, { work: true, value: email } ]

• userName (if it includes the "@" symbol)

• First email provided in the enterprise 2.0 extensions array

Name Mapping

We automatically extract display names from various SCIM name formats:

• displayName (preferred)

• name.formatted

• name.givenName + name.familyName

• givenName + familyName

Team Mapping

Profiles can be set up to automatically map a profile field to a team in the following formats:

• department

• organization

Example Requests

Create User

POST /v2/Users
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
,
"urn:myapp:schemas:extension:CustomApp:2.0:User"
],
"userName": "john.doe@company.com"
"displayName": "John Doe"
,
"title": "Software Engineer"
,
"active": true,
"emails": [{
"value": "john.doe@company.com"
,
"primary": true
,
}]
}

Update User (PATCH)

PATCH /v2/Users/123
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "replace"
"path": "title"
,
,
"value": "Senior Software Engineer"
}]
}

Deactivate User

PATCH /v2/Users/123
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "replace"
,
"path": "active"
,
"value": false
}]
}

Filter Users

GET /v2/Users?filter=userName eq "john.doe@company.com"

Group Management

Groups in SCIM map to teams in our platform. You can use group operations to create teams and manage team memberships automatically from your identity provider. Specific permissions for teams must be configured in Ivo's user management page.

When you manage groups through SCIM:

1. Creating a group creates a new team in your workspace

2. Adding members automatically assigns users to that team

3. Removing members removes users from the team

4. Deleting a group removes the team and unassigns all members

Note: Users must exist in your workspace before being added to a group. Make sure to provision users first.

List Groups

GET /v2/Groups

Get Group

GET /v2/Groups/{id}

Create Group

POST /v2/Groups

Update Group

PUT /v2/Groups/{id}    # Replace entire group
PATCH /v2/Groups/{id}  # Partial updates (add/remove members)

Delete Group

DELETE /v2/Groups/{id}

Group Attribute Mapping

Core Attributes:

Example Requests

Create a Team

POST /v2/Groups
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displaynoName": "Engineering"
,
"externalId": "eng-team-001"
,
"members": [
{
"value": "user-id-123"
,
"display": "John Doe"
}
]
}

Add Members to a Team

PATCH /v2/Groups/team-id-456
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "add"
,
"path": "members"
,
"value": [
{ "value": "user-id-789" }
]
}]
}

Remove a Member from a Team

PATCH /v2/Groups/team-id-456
{
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "remove"
,
"path": "members[value eq \"user-id-123\"]"
}]
}

Replace All Team Members

{
PATCH /v2/Groups/team-id-456
"schemas":
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "replace"
,
"path": "members"
,
"value": [
{ "value": "user-id-111" },
{ "value": "user-id-222" }
]
}]
}