Skip to main content

​
Directory sync (SCIM)

SCIM connects your directory to Gradient so that people are added, updated, and deactivated automatically. Someone joins the mapped group in your identity provider and they appear in Gradient. They leave the company and their access ends without anyone opening Gradient. Use SCIM with single sign-on. SSO decides how people prove who they are. SCIM decides who exists and what role they hold.
If your single sign-on connection uses OIDC, SCIM is the only way to drive Gradient roles from your directory. An OIDC connection cannot map groups to roles by itself. SCIM group mapping works whichever protocol people sign in with.
Directory sync is an enterprise feature. If you do not see Settings, Identity and SSO, contact your Gradient representative to turn it on for your organization.

​
What you need

  • A Gradient owner account. Identity settings are owner-only.
  • An identity provider that supports SCIM 2.0, such as Okta, Microsoft Entra ID, or Ping.
  • A working SSO connection. Set that up first.
  • A password manager or vault, ready before you start. The bearer token is shown once.

​
Part 1: Create the connection in Gradient

  1. Go to Settings, Identity and SSO.
  2. On the Directory sync (SCIM) card, click Create.
    The Directory sync SCIM card with the Create button highlighted

    The Directory sync card, before any connection exists

  3. Copy the SCIM endpoint URL and the bearer token.
The bearer token is shown once, at creation. Store it in your password manager immediately, or paste it straight into your identity provider before you leave the page. If you lose it, you create a new connection.

​
Part 2: Turn on provisioning in your identity provider

  1. Open the Gradient application you created for SSO, and find its provisioning settings.
  2. Paste the SCIM endpoint URL and the bearer token. The token is a bearer header credential, not a password field.
  3. Test the connection. Your identity provider should report success before you go further.
  4. Turn on the actions you want:
    • Create users, so new joiners appear in Gradient.
    • Update user attributes, so name changes follow.
    • Deactivate users, so leavers lose access.
  5. Assign the people or groups who should have Gradient access.

​
Part 3: Map your groups to Gradient roles

In Gradient, go to Settings, Identity and SSO and scroll to Automatic Role assignments. Click Edit, then map each directory group to one Gradient role, using the names exactly as written, in lower case: owner, admin, member, or reviewer. Most people should map to member, which can run a hiring process but cannot change the workspace.
The Automatic Role assignments card with its Edit button highlighted

Automatic Role assignments, at the bottom of the page

A person in a mapped group arrives in Gradient with that role. A person you provision without a mapped group arrives as a reviewer, which is the lowest role. Gradient records that the role was its own default rather than your instruction, so an audit shows the difference.

​
What changes in Gradient once SCIM is on

Your directory becomes the source of truth for membership. Settings, Team stops being a place where members are changed:
  • The invite and remove controls are hidden.
  • The same actions are refused by the API, with the message “Members are managed by your identity provider (SCIM). Make changes there instead.”
  • The member list still shows everyone, with their role and their status.
This is deliberate. A change made in Gradient would be overwritten the next time your directory pushed an update, and a control that silently undoes itself is worse than no control.
People provisioned by your directory appear in the Gradient member list before their first sign-in, so you can confirm a rollout worked without waiting for anyone to log in.

​
What happens when you deactivate someone

Deactivation in your directory reaches Gradient in one push. In order:
  1. Your identity provider marks the user inactive.
  2. Their Gradient account, roles, and sessions are revoked centrally, at once. They cannot sign in again.
  3. Gradient marks the member deactivated in your member list. The record stays, so the work they did and the scores they changed keep their name.
One bound worth telling your security team: a browser session already open when you deactivate someone can stay usable for up to five minutes, because Gradient validates a short-lived token locally before it checks again. No new sign-in is possible during that time. If your policy needs deactivation to take effect instantly, tell us, because there is a per-organization setting that trades a small amount of latency for it.

​
Troubleshooting

Check that the bearer token was pasted whole, with no leading or trailing space, and that it is set as a bearer token rather than a password. If the token was lost, create a new connection in Gradient and use its token.
They are probably not in a mapped group, so they arrived with the default reviewer role. Add them to the correct group in your identity provider and let it push the update. Role names must be exactly owner, admin, member, or reviewer.
That is expected once SCIM is on. Add the person in your directory instead.
Check their status. A deactivated member stays in the list on purpose, so your records keep their name, but they cannot sign in. If the status still reads active, check that your identity provider has deactivation turned on and look at its provisioning log.
Confirm the people are assigned to the Gradient application in your identity provider. Assignment, not group mapping, is what decides who is pushed.

​
What directory sync does not do

  • It does not manage candidates. Candidates are not members and never appear in your directory.
  • It does not replace your break-glass account. Keep one owner outside SCIM scope, so a directory outage cannot lock you out. See Plan for lockout.
  • It does not change how people sign in. That is your SSO connection and your authentication policy.