SCIM user provisioning
Automatically provision, deprovision, and map users to roles for Mintlify dashboard members from Okta or another SCIM 2.0 identity provider.
SCIM (System for Cross-domain Identity Management) lets admins provision and deprovision Mintlify organization members directly from your identity provider.
SCIM manages who has access to your organization. To control how users sign in, set up SSO.
Supported identity providers
Section titled “Supported identity providers”Mintlify's SCIM endpoint works with any SCIM 2.0-compliant identity provider that authenticates with a bearer token. Step-by-step instructions below cover Okta. For other providers, contact us for setup guidance.
Enable SCIM
Section titled “Enable SCIM”Open SCIM settings
In your Mintlify dashboard, navigate to the SCIM section of the Security page.
Turn on SCIM
Click Configure SCIM. Mintlify generates a SCIM base URL and a bearer token.
Add the credentials to your identity provider
Enter the SCIM base URL and bearer token into your identity provider's SCIM app configuration. See Configure your identity provider for provider-specific steps.
Configure your identity provider
Section titled “Configure your identity provider”Add a SCIM app in Okta
In Okta, under Applications, click Browse App Catalog and search for SCIM 2.0 Test App (Header Auth). This is Okta's standard integration for any SCIM 2.0 API that authenticates with a bearer token.
Add your Mintlify credentials
Under the app's Provisioning settings, enter the Mintlify SCIM base URL and bearer token. Format the token as
Bearer <token>.Enable provisioning actions
Under Provisioning to app, enable the create, update, and deactivate options you want Okta to manage. Leave Sync password off, since Mintlify doesn't use Okta-managed passwords.
Create and push groups
In Okta, use your existing groups or create new ones for each set of users you want to provision, then push those groups to the SCIM app under Push groups.
Assign users
Assign the relevant groups or individual users to the app under Assignments.
Map groups to roles
In the Mintlify dashboard, map each pushed group name to a dashboard role. See Map groups to roles.
Map groups to roles
Section titled “Map groups to roles”Assign roles to users based on their identity provider group membership.
- In the Mintlify dashboard, navigate to the SCIM section of the Security page.
- In the "Group-to-role mappings" section, click Add mapping.
- Enter the identity provider group name and select a role.
When a user belongs to multiple mapped groups, Mintlify assigns the highest-privilege role among them.
You can edit or remove a mapping at any time. This mapping is one-directional and only controls which Mintlify role a group receives. For example, suppose you map your identity provider's developers group to the editor role and later change that mapping to viewer. New members of developers become viewers in Mintlify, but the existing developers group itself is unchanged in your identity provider.
Rotate the bearer token
Section titled “Rotate the bearer token”Rotate the bearer token if it's exposed or as part of routine credential hygiene.
- Navigate to the SCIM section of the Security page.
- Click Rotate token.
- Copy the new token and update your identity provider's SCIM configuration.
Disable SCIM
Section titled “Disable SCIM”- Navigate to the SCIM section of the Security page.
- Toggle SCIM off.
Disabling SCIM stops new provisioning and deprovisioning events from your identity provider. Existing dashboard members keep their current access until removed manually or through another method.