Automatic user provisioning (SCIM)

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

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 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).
• 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.
• 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.

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.
• 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) 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) — connect your identity provider and set up sign-in
• Plans and limits — the Enterprise plan and what else it unlocks
• Members, teams, and roles — roles, minting API keys by hand, and teams
• What Claude and ChatGPT can do with CodeHerder — the connector grants deactivation revokes