Sync users from your identity provider with SCIM

SCIM directory sync is available on the Kinde Scale plan and Enterprise plan. See Kinde pricing.

SCIM (System for Cross-domain Identity Management) lets your identity provider (IdP) keep a Kinde organization’s users in sync with your directory. When someone joins, changes role, or leaves in your IdP, the change flows through to Kinde automatically, so you don’t need to add, edit, or remove users by hand.

With SCIM directory sync you can:

• Create users in a Kinde organization as soon as they’re assigned the app in your IdP.
• Keep names, email addresses, and selected profile attributes up to date.
• Suspend users when they’re deactivated or unassigned in your IdP.
• Link IdP groups to Kinde roles, so group membership controls what users can access.

Kinde supports SCIM 2.0 and works with Microsoft Entra ID (Azure AD), Okta, Google Workspace, OneLogin, JumpCloud, CyberArk, PingFederate, Rippling, and any other IdP that supports SCIM 2.0.

How SCIM directory sync works

Directory sync is set up per organization. Each organization can have one directory, and the directory is tied to one of the organization’s enterprise connections.

1. You create a directory in Kinde. Kinde gives you a SCIM Endpoint URL and a Secret Token.
2. You add these to your IdP’s SCIM provisioning settings.
3. Your IdP sends user and group changes to Kinde.
4. Kinde creates each provisioned user in the organization and gives them an identity on the enterprise connection. Users then sign in through that connection with SSO.

Kinde does not send password or SSO credentials to your IdP, and SCIM does not replace your enterprise connection. Users still authenticate through the connection. SCIM only manages who exists in the organization and what roles they have.

What you need

Link to this section

• Set up an enterprise connection for the organization (for example, SAML or Entra ID) and make sure it’s enabled. You can’t create a directory without one.
• Make sure the organization’s default roles are set the way you want. Kinde gives these roles to every user it provisions.
• Decide which existing users will be managed by SCIM. See Users who already exist in Kinde.
• Decide what to do with the organization’s current members before you create the directory. Once the directory exists, every member becomes read-only, including users your IdP will never provision. You can’t edit, suspend, or delete them in Kinde, or change their roles. Remove anyone you don’t want in the organization first, or plan to manage them through your IdP. See Directory-managed organizations.

Configuration

Link to this section

1. Create a directory in Kinde

Link to this section

1. Go to Organizations and select your organization you want to enable SCIM directory sync for.

2. In the menu, go to Provisioning > Directory.

   

   If the organization has more than one enabled enterprise connection, select the Enterprise connection that provisioned users will sign in with. If there’s only one, Kinde selects it for you.

   

3. Select Create directory. The directory creation window opens.

   

The Manage directory window shows the details your IdP needs:

• (Optional) Enter a Directory name to help you identify the directory, then select Save.
• SCIM Endpoint URL: the base URL for SCIM requests, for example https://yourbusiness.kinde.com/saml/scim/ksde_.... For Entra ID, the URL ends with /?aadOptscim062020. This flag turns on Microsoft’s SCIM 2.0-compliant behavior, so keep it.
• Secret Token: the bearer token your IdP uses to authenticate with Kinde.

You can come back to these details at any time by selecting Manage on the Directory page.

Treat the secret token like a password. Anyone who has it can create and change users in this organization.

2. Set up provisioning in your identity provider

Link to this section

In your IdP, open the application you use for the enterprise connection (or add a new SCIM provisioning app) and turn on SCIM provisioning. Enter:

IdP field (names vary)	Value
Base URL / Tenant URL / SCIM connector base URL	The SCIM Endpoint URL from Kinde
Authentication mode	HTTP header / Bearer token / OAuth bearer token
Secret token / API token / Bearer token	The Secret Token from Kinde
Unique identifier field for users	userName (usually the user’s email)

Then assign the users and groups you want to provision, and start provisioning.

Microsoft Entra ID

1. In the Microsoft Entra admin center, open Enterprise applications and select the application for your Kinde connection.
2. Select Provisioning, then set Provisioning Mode to Automatic.
3. Under Admin Credentials, paste the SCIM Endpoint URL into Tenant URL and the Secret Token into Secret Token.
4. Select Test Connection, then Save.
5. Assign users and groups under Users and groups, then turn Provisioning Status on.

Okta

1. In the Okta Admin Console, open the application for your Kinde connection and select General > Edit, then turn on SCIM provisioning.
2. On the Provisioning tab, enter the SCIM Endpoint URL as the SCIM connector base URL and userName as the Unique identifier field for users.
3. Under Supported provisioning actions, select Push New Users, Push Profile Updates, and Push Groups.
4. Set Authentication Mode to HTTP Header and paste the Secret Token into Authorization.
5. Select Test Connector Configuration, then Save.
6. Under Provisioning > To App, turn on Create Users, Update User Attributes, and Deactivate Users.
7. On the Push Groups tab, select Push Groups, then find and push each group you want to map to a Kinde role. Pushed groups appear under Synced Groups on the Directory page.

Your IdP’s first sync can take a few minutes. Provisioned users appear on the organization’s Users page, and the Synced users and Synced groups counts on the Directory page update as requests arrive.

3. Link directory groups to Kinde roles (optional)

Link to this section

When your IdP pushes groups, they appear on the Directory page under Synced Groups. Groups don’t create roles in Kinde. Instead, you link each group to one or more existing roles, and Kinde gives those roles to the group’s members in this organization.

1. On the Directory page, find the group in Synced Groups.
2. Select the three dots menu on the group, then select Link to role.
3. Select one or more Roles, then select Save.

When a user is added to the group, they get the linked roles. When they’re removed from the group, or the group is deleted, they lose those roles. The exception is a role they also get from another linked group they still belong to.

To stop a group from granting roles, select Unlink all roles from the group’s menu. Members lose the access those roles gave them.

4. Map user attributes (optional)

Link to this section

Kinde maps these SCIM user attributes automatically:

SCIM attribute	Kinde field
emails (the primary email, or the first one)	Email
userName	Used as the email if your IdP doesn’t send emails
name.givenName	First name
name.familyName	Last name
active	Suspended status (false suspends the user)
externalId	Stored to match the user with your IdP

An email address is required for every user.

Enterprise attributes

When you create a directory, Kinde adds an Enterprise directory category of user properties and maps the SCIM enterprise extension (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User) to it:

SCIM attribute	Kinde user property	Property key
employeeNumber	Employee number	kp_usr_employee_number
costCenter	Cost center	kp_usr_cost_center
organization	Organization	kp_usr_organization
division	Division	kp_usr_division
department	Department	kp_usr_department
manager	Manager	kp_usr_manager

You can add these properties to tokens like any other user property.

Custom attributes

Kinde reads custom attributes from the custom extension schema urn:custom:extension:2.0:User. Neither Entra ID nor Okta sends custom attributes by default, so first add each attribute to your IdP’s SCIM app under that schema. The examples below use an attribute called badgeNumber.

In Microsoft Entra ID:

1. In your enterprise application, go to Provisioning > Mappings and select Provision Microsoft Entra ID Users.
2. Select Show advanced options > Edit attribute list for your app.
3. Add an attribute with the Name urn:custom:extension:2.0:User:badgeNumber and the Type that matches your data (for example, String), then select Save.
4. Back on the Attribute Mapping page, select Add New Mapping. Choose the Entra ID Source attribute and set Target attribute to urn:custom:extension:2.0:User:badgeNumber. Select OK, then Save.

In Okta:

1. Go to Directory > Profile Editor and select your app’s user profile.
2. Select Add Attribute. Enter a Display name and Variable name, set External name to badgeNumber and External namespace to urn:custom:extension:2.0:User, then select Save.
3. Open the app’s Provisioning tab, go to To App, and map an Okta user attribute to the new attribute under Attribute Mappings.

Once Kinde receives a custom attribute, it’s listed under Custom attribute mapping on the Directory page. Kinde ignores attributes sent under any other custom schema URN. Map each attribute to a Kinde user property:

1. On the Directory page, under Custom attribute mapping, find the attribute.
2. Select the three dots menu, then select Map to user property.
3. Select the User property to sync the attribute to, then select Save.

Mapped values sync whenever a user is created or updated. Attributes only appear in the list after your IdP has sent them for at least one user, so provision a test user first. Boolean properties are only offered for attributes Kinde has received as true or false.

Other SCIM attributes, such as phone numbers, addresses, and titles, are stored with the user’s SCIM record but aren’t mapped to Kinde fields. To see everything your IdP sent for a user, open the user’s profile and select View SCIM user data.

What happens when users change in your IdP

Link to this section

Change in your IdP	What happens in Kinde
User assigned to the app	The user is created in the organization with the organization’s default roles and an identity on the enterprise connection.
Profile updated	Name, email, and mapped attributes are updated. A changed email address is added to the user as a confirmed email.
User deactivated or unassigned (active: false)	The user is suspended and can’t sign in. Group memberships and the roles they grant are kept. Okta and Entra ID send this update when you unassign a user from the app.
User reactivated (active: true)	The user is unsuspended, unless an admin suspended them in Kinde.
User deleted (SCIM DELETE request)	The user is suspended and removed from all directory groups, so they lose any roles granted by those groups. The user record stays in Kinde, so their history and references are kept. If your IdP provisions them again, they’re restored.
Group membership changed	Roles linked to the group are added or removed.

Group changes while a user is unassigned

Okta and Entra ID stop sending group changes for a user once they’re unassigned from the app. If the IdP admin removes an unassigned user from a group, Kinde isn’t told, so the user keeps that group’s roles while suspended. This only matters if the user is reassigned later. The IdP admin can clear it by re-pushing the group, or by removing the user from groups before unassigning them.

When SCIM changes a user, Kinde sends a user.updated webhook event. SCIM creates and deletes don’t send user.created or user.deleted events. Instead, a SCIM delete sends user.updated with the user suspended.

Directory-managed organizations

Link to this section

Once an organization has a directory, your IdP is the source of truth for its members. To stop changes in Kinde from being overwritten by the next sync, Kinde makes the organization’s users read-only:

• User details can’t be edited, and the user’s profile shows that they’re managed by the directory.
• Users can’t be added, invited, deleted, or suspended in the Kinde admin area, through the Management API, or in the self-serve portal.
• Roles in the organization can’t be changed manually. Use group-to-role links instead.
• Identities can’t be added, changed, or removed.
• A directory-managed user can only belong to that one organization. They aren’t added to other organizations, including through verified domain auto-join.

This applies to every member of the organization, including members who were added before the directory was created. Make changes in your IdP instead.

Users who already exist in Kinde

Link to this section

Kinde matches SCIM users to existing users through their enterprise identity, not their email address alone:

• Pre-provisioned users. If you’ve already added an enterprise identity for the user on the directory’s connection, SCIM takes over that user.
• Users with another sign-in method. A user with the same email who signs in with a password, email code, or social sign-in isn’t linked. SCIM creates a separate user.
• Users who have already signed in through the connection. Your IdP gets a 409 User already exists error for these users.

To avoid duplicates, set up directory sync before users start signing in through the enterprise connection, or migrate them to an enterprise identity first.

Manage the directory

Link to this section

View SCIM request logs

Link to this section

To see every request your IdP has sent, go to the organization and select Provisioning > Logs. Select a request to see its method, path, response status, request body, and any error Kinde returned. This is the first place to look if users aren’t syncing.

The Status shown in the Manage directory window reflects the most recent request: Active after a successful request, or Error with the HTTP status code after a failed one.

Regenerate the secret token

Link to this section

If the token may have been exposed, regenerate it.

1. On the Directory page, select Manage.
2. Select Regenerate secret token, then confirm.
3. Copy the new Secret Token into your IdP.

The old token stops working immediately, so provisioning fails until you update your IdP.

Change the enterprise connection

Link to this section

You can change which enterprise connection provisioned users sign in with until Kinde receives the first SCIM request. On the Directory page, select a connection under Enterprise connection for provisioned users, then select Save connection.

After the first request, the connection is locked. To use a different connection, delete the directory and set it up again.

If the directory’s enterprise connection is deleted, provisioning stops working until you select another connection on the Directory page.

Delete a directory

Link to this section

You can delete a directory with the Management API. Deleting a directory removes its SCIM user and group records and stops your IdP from syncing. Users, their organization membership, and their roles stay in Kinde.

You can also create, list, update, and regenerate tokens for directories through the Management API. These endpoints require the read:scim_directories, create:scim_directories, update:scim_directories, and delete:scim_directories scopes.

SCIM API reference for IdP integrations

Link to this section

If you’re building or configuring a custom SCIM integration, Kinde’s SCIM service supports:

Feature	Support
Resources	/Users, /Groups
Discovery	/ServiceProviderConfig, /Schemas, /ResourceTypes
Operations	GET, POST, PUT, PATCH, DELETE
Authentication	Authorization: Bearer <secret token>
Filtering	userName eq "..." for users, displayName eq "..." for groups (case-insensitive)
Pagination	startIndex and count (maximum 100 per page)
Not supported	Bulk operations, sorting, ETag preconditions, password changes, /Me

Errors use the standard SCIM error format (urn:ietf:params:scim:api:messages:2.0:Error). Common errors:

Status	Meaning
401	The bearer token is missing or wrong. Check the token, or regenerate it.
404	The directory, user, or group doesn’t exist.
409	The user, userName, email, or group name is already in use.
400	The request is invalid, for example a user without an email address, or the directory has no enterprise connection.

Troubleshooting

Link to this section

You see an upgrade prompt on the Directory page

Your plan doesn’t include SCIM directory sync. Upgrade to the Scale plan or Enterprise plan to create a directory.

“Set up an enterprise authentication connection before configuring directory sync”

The organization needs an enabled enterprise connection. Add or enable one under the organization’s Authentication settings.

Your IdP’s connection test fails with 401

The secret token is wrong or has been regenerated. Copy the current token from Manage directory into your IdP.

Users aren’t being created

Check Provisioning > Logs for the failed requests. Common causes:

• The user has no email address in your IdP.
• The user already signed in through the enterprise connection before SCIM was set up (409 User already exists).
• The user is already managed by a directory on another organization.

Duplicate users

The user had a non-SSO identity (such as an email and password) before SCIM was set up. See Users who already exist in Kinde.

Roles aren’t being assigned

Check that the group is linked to a role under Synced Groups, and that your IdP is pushing that group and its members.