SCIM user provisioning

In preview: Contact your Bird representative to enable SCIM for your organization. Provisioning supports users; SCIM group provisioning is not supported yet.

Use SCIM 2.0 to create users, update their roles, and remove their access when they leave. Each organization has one authoritative directory. Deactivating or deleting a directory user removes all their access to that organization, including manually assigned roles. Their Bird account and access to other organizations stay available.

Assign a role as part of setup. A person can appear in Managed users with no access: SCIM creates their directory record, and role values grant organization or workspace access. A person without grants does not appear in the team list.

Before you start

You need an organization owner account, an active SSO connection, and a verified domain for each email address you provision. Keep an organization owner outside your provisioning assignments for recovery access: SCIM cannot adopt, change, or deactivate owners.

You also need permission to configure provisioning in your identity provider. Use a test user before assigning your team.

Connect the directory

1. Open SCIM provisioning in your organization sidebar. From a workspace, open Settings > SCIM provisioning.
2. Select Set up directory, choose the active SSO connection, and select Enable provisioning. This connection cannot be changed or deleted while it owns the directory.
3. Copy the SCIM base URL exactly as shown, including its regional host and connection ID.
4. Select Create SCIM key and optionally choose an expiry date. The key is named SCIM key. An expiry date takes effect at 00:00 UTC that day; leaving it blank creates a key without an expiry.
5. Save the key in your secret manager, then enter it as the bearer token in your provider's provisioning settings. The full key is shown once.
6. Map your user's email to userName and their enabled status to active. You can also send externalId, displayName, and name attributes.
7. Follow your provider's setup steps below to assign a role and provision one test user. Check Managed users and open their record to compare Directory roles with Current direct grants. For a workspace role, also open that workspace's Settings > Team and confirm the person appears with the expected access.

The key is dedicated to this organization's SCIM directory. Each organization has one current SCIM key. Use rotation to replace it. A regular workspace API key or organization master key cannot replace it.

Configure Okta or Microsoft Entra ID

For Okta, follow Set up SCIM with Okta. The walkthrough adds provisioning to a SAML application and defines named role choices for direct or group assignments. If your connection already works but a user has no access, check the role choices and assignment settings.

For Microsoft Entra ID, follow Set up SCIM with Microsoft Entra ID. The walkthrough configures the required URL flag and attribute mappings, defines named app roles, and combines workspace access through security group assignments. Verify role changes and deactivation through automatic provisioning cycles.

Provider templates differ in the attributes they expose. Map Bird role values to the SCIM roles attribute. Bird accepts objects containing value and Okta's array of role strings. Inspect the provisioning payload or logs when the user appears without the expected roles.

Assign roles across workspaces

Send the user's access as a multi-valued SCIM roles attribute. The dashboard's Role values section gives you values to copy:

For one person to be an administrator in workspace A and an analyst in workspace B, map two values into that person's application profile. Replace both placeholders with the workspace IDs from Role values:

{
  "roles": [
    { "value": "workspace:<workspace-a-id>:admin" },
    { "value": "workspace:<workspace-b-id>:analyst" }
  ]
}

Send at most one organization role and one role per workspace. A workspace must belong to this organization. Owner and platform roles are not accepted. A new user without role values has no organization or workspace grants.

For Okta, select roles on user or group assignments. Okta can combine role values from multiple assigned groups and sends them as an array of strings. These groups stay in Okta; Bird receives each person's resulting role values.

You can edit roles manually in Bird. The next successful SCIM update, including a profile update, restores the directory's desired roles in the scopes it manages. Manual grants in other scopes remain while the user is active. Sending roles: [] removes the directory's managed grants; omitting roles retains its previous desired roles.

Check sign-in and deactivation

SCIM-managed users can sign in through SSO without receiving additional default SSO roles. Default just-in-time provisioning still applies to users outside the directory. Multiple SSO connections can provide login while one directory controls provisioning.

Disable the test user in your provider and confirm they can no longer access this organization, including through an existing session. Other organizations remain accessible. An inactive user remains listed and can be reactivated. A SCIM delete removes the directory record from the list; provisioning that person again creates a new directory record and can reuse their existing Bird account.

Maintain the connection

Use Rotate on a key to create a replacement. The replacement has no expiry, even if the old key expires. Choose Immediately or After 24 hours for when the previous key stops working, then replace the token in your provider. The old key stops at that time or its existing expiry, whichever comes first. Rotating again revokes any older overlap key, so only the current key and its immediate predecessor can work together.

Revoke makes Bird reject requests using that key; cached or in-flight requests may still complete. Pause provisioning rejects all SCIM requests, including deactivation, without revoking the key. Your provider can continue sending requests and report sync failures. Neither action removes current user grants or restores access for previously deactivated users. Resume provisioning to use the same unexpired, non-revoked key again, and let the provider send updates to reconcile changes made while paused.

Suspending the SSO connection also pauses provisioning, including when the organization has no verified email domains left. After restoring the domain and activating SSO, resume provisioning from the SCIM page.

Provisioning activity shows the latest request, successful request, and failed request. A successful request can be a read; it does not prove a full sync completed. For failures, check the provider's provisioning logs: verify the key and URL, the user's verified email domain, and role values. An owner or conflicting identity cannot be managed through SCIM.

Next steps

• Single sign-on: configure and manage your organization's login connections.
• Users, teams & roles: review organization and workspace access.