Connect Directory Sync (SCIM)

Mint a token and connect your provider

In the Developer Console, Access Control → Integrations → Directory Sync is one page with three tabs: Connection, Groups, and Activity. It provisions and deprovisions identities in this Environment from Okta, Entra ID, or any SCIM 2.0 provisioner. Directory Sync is a Pro feature; on a Free account the page says so and offers no actions.

Application: Developer Console
Path: Access ControlIntegrationsDirectory Sync
Opens with: sso.view Read SSO connections, verified domains, the custom auth domain, and directory sync.
Context: Select an Application and an Environment in the switcher first; the page belongs to that Environment.

Mint a token and connect your provider

Open Directory Sync from the left nav under Access Control → Integrations. On Connection, with nothing minted yet, the page reads No SCIM tokens yet.

Click Mint SCIM Token and name it. The token is revealed once; copy it now. The table then lists it by name and Token Prefix, with Last Used reading Never until your provider first calls.

In your identity provider, point SCIM provisioning at the full base URL shown when the token was minted (https://<api host>/scim/v2/directories/<id>) using the token. Pushed users appear in the Environment's identities; pushed groups appear on the Groups tab.

Map groups to roles

A pushed group starts Unmapped. Mapping it to a role at a node grants every current member that role there, and membership pushes keep the grants in sync afterwards. A member the grant rules refuse is skipped and the rest are granted: somebody with no membership in effect in the organization the node sits beneath, or anybody at all once the role has been deactivated.

Map groups to roles

On Groups, click Map role on a group. In Map SCIM group to a role, choose the role and the node, and save. The dialog warns that every current member is granted the role on save; a Group mapped. Members granted the role. toast appears and the row shows the role.

Edit mapping changes the role or node for the whole group.

Unmap removes the mapping. The confirmation states that every member granted the role through the group loses it immediately, that group membership itself is unchanged, and that this cannot be undone. A Mapping removed. toast appears.

The Activity tab is the feed of the directory: what your provider has done (users provisioned, updated, deprovisioned, and reactivated; groups created, updated, deleted, mapped, and unmapped; and any sync that failed), and the changes made to the connection itself (the directory set up, and tokens created, replaced, and revoked). The provider's activity reaches your webhooks as the scim.* events, and what it changed reaches them as the ordinary identity, membership and assignment events marked source: "scim".

Let an organization connect its own provider

An Environment that uses organizations has a second kind of directory: one per organization. Each directory answers only for the organization it serves, so no organization's provider ever sees another's people. What you always decide is which of your roles that provider may hand out; the connection itself can be set up by the organization's administrator from their portal or by you here.

Application: Developer Console
Path: Access ControlOrganizations
Opens with: env_organizations.view Read the Environment's organizations, their members, and their invitations.
Context: Select an Application and an Environment in the switcher first; the page belongs to that Environment.

Let an organization connect its own provider

Open the organization from Organizations and go to its Directory sync tab. The first card, Roles their provider may grant, shows the Environment's list with a From Environment badge when one is set; otherwise it is empty until you choose: until then the organization's administrator sees a page saying directory sync is not available to them, and there is nothing for them to connect.

Click Choose roles and tick the roles this organization's provider may grant. Pick one as the role people arrive with: somebody the provider pushes becomes a member holding it, unless a mapped group gives them another. Exactly one role carries it.

Connect the provider. Either the organization's administrator does it from their own portal, or you click Connect a directory here and then Create token, and hand the SCIM base URL and the token to whoever configures their provider. The token is shown once.

Verify the organization's email domain before its provider pushes anybody (Policy tab, Domains, or the portal's Single sign-on page). A directory adds people on the organization's verified domains and refuses everybody else; somebody outside them joins by invitation, and once they belong the provider can manage them too.

Once connected, the Connection card shows the SCIM base URL and the tokens (replace one without an outage, or revoke it); Groups lists the groups their provider has pushed, each of which you or they can map to one of the roles you listed; and Activity shows that organization's own directory events and no other's: what their provider pushed, and the changes to the connection, its tokens, and the roles it may grant. It is the answer to “why did their sync stop”, and it needs env_identities.view as well, because the rows name the people their provider pushed.

Untick a role to withdraw it: groups mapped to it are unmapped, and their members stay in the organization on the role people arrive with. Choosing a different role people arrive with moves everybody who arrived onto it. Ticking no role at all removes the organization's own list, and it goes back to the Environment's list. With no Environment list that withdraws directory sync from the organization, which is refused while their directory is still running: end the connection first.

End the connection on the Connection card stops the provider pushing. Everybody it created keeps their account and their membership; what ends is the provider's reach.

Revoke a token

Revoking ends the connection at once.

Revoke a token

On Connection, click Revoke on the token. The Revoke SCIM Token dialog warns that provisioning requests using it stop working immediately and that a new token must be minted to reconnect. Confirm; a SCIM token revoked. toast appears.

If you don't see this

Each control on this page exists only for someone who may use it. When something described above is missing, one of these is why:

Directory Sync is not under Integrations. Either no Application and Environment is selected yet, or your administrator role does not carry sso.view.

There is no Mint SCIM Token, Map role, Unmap, or Revoke. You hold sso.view but not sso.manage.

An organization has no Directory sync section. Either the Environment does not use organizations, or your role does not carry env_organizations.view.

There is no Choose roles on an organization's Directory sync. You hold env_organizations.view but not env_organizations.manage.

An organization's Directory sync shows no activity. Either their provider has not run yet, or your role carries env_organizations.view but not env_identities.view. The feed names people, so it rides the identities capability.

The Activity feed shows the connection's changes but not who your provider provisioned. The Environment is marked production and your role does not carry production_identities.access: events naming people there are withheld, and the directory's own events (set up, tokens created, replaced or revoked) stay visible.

The page says Directory Sync is a Pro feature. The Account is on the Free plan; upgrade from the Admin Workspace's Billing page.

Groups is empty. Nothing appears until your identity provider pushes a group over SCIM using the token.

Set up an SSO connection →

Manage organizations →

Webhook event types →

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.