# Automatic user provisioning (SCIM)

Let your identity provider create, update, and deactivate CodeHerder accounts automatically, on the Enterprise plan.

Source: https://codeherder.com/docs/scim/

Let your identity provider create, update, and deactivate CodeHerder accounts automatically, on the Enterprise plan.

Automatic user provisioning uses the SCIM standard to let your identity provider manage CodeHerder accounts directly. It creates an account when someone joins, keeps their name in sync, and deactivates the account the moment they leave, all without an admin doing it by hand.

SCIM rides on top of a [Single sign-on (SAML)](https://codeherder.com/docs/sso/) connection, so set that up first. It also needs the **Enterprise** plan in its own right. A workspace can hold SAML without SCIM, or neither, so check both before you start. See [Plans and limits](https://codeherder.com/docs/plans-and-limits/#what-your-plan-unlocks).

## Minting a token

There’s no app screen for this yet. You mint a SCIM token with a direct request, using your own CodeHerder API key:

```
curl -X POST https://api.codeherder.com/v1/sso-connections/<connectionId>/scim-token \
  -H "Authorization: Bearer $CH_TOKEN"
```

You’ll need your connection’s id for that URL. List it first:

```
curl -H "Authorization: Bearer $CH_TOKEN" \
  https://api.codeherder.com/v1/workspaces/<workspaceId>/sso-connections
```

Any workspace id under your account’s top-level workspace works, since SSO connections are account-wide, not per-workspace. The `id` field on the one connection returned is what the SCIM routes call `<connectionId>`.

Only an **owner** or **admin** of your account’s top-level workspace can mint or revoke a SCIM token, and only a person — an agent’s credentials don’t work here. See [Credentials and profiles](https://codeherder.com/docs/credentials/#api-key) for setting up your own API key.

The response carries `token`, `expiresAt`, and `createdAt`. **Copy the token now.** CodeHerder shows it once, in that response, and never displays it again. By default a token lasts one year from when you mint it; read `expiresAt` for the exact deadline.

Minting again immediately retires whatever token was live before. Your identity provider stops authenticating with the old one the moment the new one exists, so update it there right away. Sending a `DELETE` to the same address revokes the current token outright and answers with the connection either way, including when no token was live to revoke.

## Handing it to your identity provider

Give your identity provider two things: the SCIM base URL and the token you minted.

- **Base URL:** `https://api.codeherder.com/scim/v2` (a self-hosted deployment uses its own address — see [Self-hosted deployment](https://codeherder.com/docs/self-hosting/)).
- **Authentication:** bearer token, using the SCIM token from above.

Most identity providers check the connection before saving it by requesting its capabilities. CodeHerder’s SCIM implementation supports filtering and profile updates through `PATCH`. It doesn’t support bulk operations, sorting, or ETags.

## What your identity provider can do

CodeHerder’s SCIM implementation manages **users only** — there’s no group provisioning.

| Action | What happens |
| --- | --- |
| **Create** a user | Provisions the account the same way an ordinary invitation does: the **member** role in your top-level workspace, and the same invitation email. |
| **Read or list** users | One filter is supported, `userName eq "person@example.com"`. Paging uses a 1-based `startIndex` and a page size `count`, which defaults to 200 and tops out at 500. |
| **Update** a user | Renames `userName`, `displayName`, or `name.formatted`. |
| **Deactivate** a user | Either a `DELETE`, or a profile update that sets `active` to `false`. |
| **Reactivate** a user | A profile update that sets `active` to `true`. |

Creating a user needs `userName`, the person’s email address. Everything else is optional: if you don’t send `displayName` or `name.formatted`, CodeHerder falls back to the part of the email address before the `@`. An email address already registered anywhere in CodeHerder is refused, since addresses are unique across the whole product, not just your workspace. Your plan’s member limit applies to accounts SCIM creates, the same as any invitation you send by hand.

A profile update that doesn’t mention `active` at all leaves the person’s status exactly where it was. Syncing someone’s name never reactivates or deactivates them as a side effect.

## What deactivating someone does

This is the part your identity provider admin should understand well, because it goes further than switching off sign-in:

- Their workspace role is revoked.
- **Every** API key they hold is revoked, not only ones related to SCIM.
- **Every** connection they’ve granted to Claude or ChatGPT is revoked too — see [What Claude and ChatGPT can do with CodeHerder](https://codeherder.com/docs/mcp-tools/).
- They’re signed out everywhere.

Reactivating someone restores their role and lets them sign in again, but it does not restore a revoked API key or connector grant. They set those up again from scratch, the same as anyone doing it for the first time — see [Minting API keys](https://codeherder.com/docs/members-and-teams/#minting-api-keys).

Deactivating through SCIM never erases the account. A later read still returns the person, with `active` set to `false`, because their history stays attached to the work they did.

## Limits

- SCIM only sees your account’s **top-level workspace roster**. Someone whose only membership is in a workspace nested underneath it is invisible to SCIM — listing, reading, updating, or deactivating them through SCIM behaves as if they don’t exist. Manage those people from the Members page instead.
- There’s no group provisioning and no bulk operations. Team membership inside CodeHerder stays something you manage directly — see [Teams](https://codeherder.com/docs/members-and-teams/#teams).
- A **disabled** connection stops SCIM as well as sign-in. A **pending** one — not yet enabled for sign-in — still serves SCIM, so you can wire up provisioning before you cut sign-in over.
- SCIM requests are rate-limited per connection. If your identity provider bursts a large sync, a handful of requests may be throttled and worth a retry.

## Troubleshooting

| Your identity provider reports | What’s happening |
| --- | --- |
| `401` unauthorized | No bearer token was sent, or the one that was sent is malformed, unrecognized, revoked, or expired. Mint a fresh token and update your identity provider; if the current one is close to a year old, check `expiresAt` to see if that’s why. |
| `402` payment required | Your account’s plan no longer includes SCIM provisioning — it needs Enterprise. |
| `403` forbidden, on any request | The token is valid, but its connection is disabled or gone. Re-enable the connection on the [Single sign-on (SAML)](https://codeherder.com/docs/sso/) page, or set up a new one. |
| `403` forbidden, on creating a user | Your plan’s member limit is reached. Free up a seat or upgrade your plan. |
| `409` conflict, on creating a user | That email address is already registered somewhere in CodeHerder. |
| `429` too many requests | Sync traffic hit the per-connection rate limit. Retry the throttled requests. |
| A filter is rejected | Only `userName eq "..."` is supported — no other field or operator. |
| Group sync fails (`501`) | Group provisioning isn’t implemented. Manage team membership in CodeHerder directly. |

**Provisioning stops working right after you offboard an admin.** Deactivating someone revokes every credential they hold, including a SCIM token they minted themselves — that shows up as `401`, the same as any other revoked token. Mint a new token as a different admin and update your identity provider.

## Related guides

- [Single sign-on (SAML)](https://codeherder.com/docs/sso/) — connect your identity provider and set up sign-in
- [Plans and limits](https://codeherder.com/docs/plans-and-limits/) — the Enterprise plan and what else it unlocks
- [Members, teams, and roles](https://codeherder.com/docs/members-and-teams/) — roles, minting API keys by hand, and teams
- [What Claude and ChatGPT can do with CodeHerder](https://codeherder.com/docs/mcp-tools/) — the connector grants deactivation revokes