System for Cross-domain Identity Management (SCIM) 2.0 lets your identity provider provision and deprovision users in your Redocly organization automatically. SCIM works alongside single sign-on (SSO). Users still sign in through your IdP. SCIM keeps organization membership in sync with your directory.
Each SCIM integration is tied to a specific identity provider you added in Reunite (Corporate or Guest, SAML 2 or OpenID Connect). The SCIM base URL is unique to that identity provider.
This is a feature in early access. It may not be available for your organization yet, and its behavior may change before general availability.
To request access to this feature, contact our Support team.
Make sure you have the following:
- a SAML 2 or OpenID Connect identity provider added in Reunite for the organization you want to provision users into
ownerrole in your organization- an organization API key you can use for SCIM authentication. Store it securely and use the key value as the bearer token. If you later rotate or revoke that key, update the bearer token in your identity provider’s SCIM provisioning application so provisioning keeps working
- confirmation from Redocly that SCIM has been enabled for your organization
- Log in to Redocly and access your organization's Overview page.
- Select SSO and login in the navigation menu on the left side of the page.
- Under Identity Provider, open the Corporate or Guest provider you want to connect to SCIM (for example, click Edit). If you use SAML 2 or OpenID Connect, you are taken to the corresponding identity provider form.
- Select Enable SCIM 2.0.
- Copy the SCIM endpoint value shown on the form. Enter this URL in your identity provider’s SCIM or provisioning settings.
Your identity provider must send an Authorization header that carries your organization API key. Use the Bearer format followed by a space and the full API key string (the same value you copy when you create a key in API keys).
Create or rotate keys under API keys in your organization settings. From more information about API keys in your Redocly products, see Manage API keys.
If you rotate or revoke the organization API key used for SCIM, put the new key value into your identity provider’s SCIM provisioning settings (the same place you configured the bearer token). The IdP's SCIM requests fail and automatic provisioning stops until you provide a valid key.
Redocly follows SCIM 2.0 Core User and Group resources. Map your identity provider’s attributes to the SCIM fields so the provisioning matches data in Redocly.
Redocly reads these SCIM User attributes:
- userName or emails (email address in Redocly): If userName is a valid email, it is used. Otherwise Redocly uses the emails list. Prefer the entry marked primary, or the first email in the list.
- externalId (IdP user id): Required for create and update. Links the directory user to SSO for this identity provider.
- name.givenName and name.familyName (first and last name): Optional.
- active (organization membership): true provisions the user into your Redocly organization. false removes them from the organization (deprovisioning).
Other SCIM User attributes (for example displayName, title, locale, timezone, profileUrl, name.middleName) are not saved to the Redocly user profile. Your IdP may still send them.
Redocly maps SCIM Groups to organization teams:
- displayName (team name): Becomes the team name in Redocly.
- members (team membership): Your IdP can add or remove members with SCIM Group updates when it supports those operations.
The exact behavior depends on which SCIM operations your IdP sends. If you have synchronization issues your environment, review the attribute mapping in your IdP.
In your identity provider’s admin console, create or edit a SCIM provisioning application (sometimes called automated provisioning or directory sync). Use the SCIM endpoint from Reunite as the provisioning base URL, and configure bearer token authentication with your organization API key.
Exact field names and steps depend on your IdP. After you save your Reunite settings and your IdP configuration, run your provider’s test or sync flow if available to confirm connectivity.
Deprovisioning removes the user from your Redocly organization when your IdP sets active to false or unassigns them from the provisioned application, depending on how your IdP implements SCIM.
- Add an identity provider - Add or edit SAML 2 and OpenID Connect identity providers in Reunite
- Manage API keys - Create and revoke organization API keys used for SCIM authentication
- Configure SSO - Choose which identity providers apply to each project in
redocly.yaml - Single sign-on (SSO) concepts - Learn how Corporate and Guest identity providers work with Reunite and projects
- SSO configuration reference - Technical reference for SSO options in your project configuration