> ## Documentation Index
> Fetch the complete documentation index at: https://trygradient.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Directory sync (SCIM)

> Let your identity provider create, update, and deactivate Gradient members automatically

# 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](/docs/guides/sso). SSO decides how people prove who they are. SCIM
decides who exists and what [role](/docs/concepts/members-and-permissions) they hold.

<Note>
  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.
</Note>

<Note>
  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.
</Note>

## 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**.

   <Frame caption="The Directory sync card, before any connection exists">
     <img src="https://mintcdn.com/gradient-fc5b2665/Ym5_OoSvO1_m1jVz/images/identity/scim-create.png?fit=max&auto=format&n=Ym5_OoSvO1_m1jVz&q=85&s=8b8ef30d5f4079886baa939fc2810908" alt="The Directory sync SCIM card with the Create button highlighted" width="1600" height="433" data-path="images/identity/scim-create.png" />
   </Frame>

3. Copy the **SCIM endpoint URL** and the **bearer token**.

<Warning>
  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.
</Warning>

***

## 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.

<Frame caption="Automatic Role assignments, at the bottom of the page">
  <img src="https://mintcdn.com/gradient-fc5b2665/Ym5_OoSvO1_m1jVz/images/identity/automatic-role-assignments.png?fit=max&auto=format&n=Ym5_OoSvO1_m1jVz&q=85&s=0a3d34310e057f12ebd5a8c7f985823c" alt="The Automatic Role assignments card with its Edit button highlighted" width="1600" height="299" data-path="images/identity/automatic-role-assignments.png" />
</Frame>

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.

<Note>
  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.
</Note>

***

## 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.

<Warning>
  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.
</Warning>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The connection test fails in my identity provider">
    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.
  </Accordion>

  <Accordion title="Someone was provisioned but has the wrong role">
    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`.
  </Accordion>

  <Accordion title="I cannot invite a member in Gradient">
    That is expected once SCIM is on. Add the person in your directory instead.
  </Accordion>

  <Accordion title="A leaver still appears in the member list">
    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.
  </Accordion>

  <Accordion title="Nobody is syncing at all">
    Confirm the people are assigned to the Gradient application in your identity provider.
    Assignment, not group mapping, is what decides who is pushed.
  </Accordion>
</AccordionGroup>

***

## 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](/docs/guides/sso#plan-for-lockout-before-you-enforce).
* **It does not change how people sign in.** That is your SSO connection and your authentication
  policy.