A SCIM request returns 401

Your identity provider reports that provisioning is failing, or its setup wizard will not complete. SCIM produces exactly two authentication messages and they mean different things, so start by getting the exact one out of your provider's log rather than working from 401.

401  missing or invalid Bearer token
401  invalid SCIM token

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail":  "<the message>",
  "status":  "401"
}

Note that status is a string in that body, per the standard. A client parsing it as a number will fail on the error rather than on the cause, which produces a confusing second-order failure.

`missing or invalid Bearer token` — the header is wrong

This is emitted before the token is looked up at all. It means the Authorization header was absent, did not begin with the exact string Bearer including the space, or carried fewer than eight characters after it. Four causes, in the order they occur:

1. The scheme is lower case. Bearer <token> works and bearer <token> does not. The comparison is case-sensitive, and this trips up hand-written integrations more often than anything else on this page.
2. No header is being sent at all. Some providers only attach credentials once the connection has been marked healthy, so a wizard that failed its first probe never sends one afterwards. Check the provider's outbound request log rather than its configuration screen.
3. The provider is using basic authentication. The only scheme accepted here is OAuth bearer token; /ServiceProviderConfig advertises that and nothing else. If your provider offers a username-and-password option, it is the wrong one.
4. The value was truncated on paste. A token is 43 characters after its prefix. Anything obviously short is a paste that lost its tail.

`invalid SCIM token` — the header is right and the token does not resolve

The header parsed, the token was looked up, and no active record matched. Four conditions produce this and they are deliberately indistinguishable — same message, same timing — because anything else turns the endpoint into a way of testing which tokens are real.

• It never existed — a typo, or a token from a different tenant.
• It was revoked. Revoked tokens are kept rather than deleted, so they still appear in the token list with a revocation timestamp. Check the list before assuming it was never created.
• It expired, if you set an expiry when you minted it.
• It was disabled.

A valid token begins zqscim_ followed by 43 characters. Only its hash and its first fourteen characters are kept, so you can identify one in a list without being able to recover it. If you have lost it, mint a new one and revoke the old — there is no way to read it back.

Minting is at POST /api/v1/organizations/{orgID}/scim/tokens and needs sso.write; listing needs sso.read and revoking needs sso.delete. It is gated on the single sign-on family rather than something weaker because a SCIM token can create users and memberships — an ungated mint would let any member of a tenant provision themselves an administrator without ever leaving it.

Two validation refusals you may meet while minting: 400 scim token: organization id is required and 400 scim token: name is required.

Two failures that are not 401 and look like one

A `500` that is a mapping mistake on your side

The filterable attributes are an allow-list, and that is a security decision rather than tidiness — answering an unknown attribute with an unfiltered result would hand over the whole directory to a single probe. On users: userName, externalId, active, emails.value, name.givenName, name.familyName, displayName, id. On groups: displayName, externalId, id. Anything else is refused.

It fails loudly because it used to fail quietly: an unparseable filter was turned into a substring search for the filter's own text, which matched nothing for every real provider probe — so an Okta import reported 0 users with nothing in any log to explain why. A noisy 500 is a bad answer and a quiet zero was a worse one.

Two `404`s your provider's wizard will hit

There is no /Schemas endpoint and no /ResourceTypes endpoint. The standard lists both as discovery endpoints and a provider that probes them gets a 404.

Most providers tolerate this and carry on using /ServiceProviderConfig. A few refuse to complete a setup wizard that expects a schema document. If yours will not finish its configuration step and you have ruled out the token, this is the likely reason — configure the attribute mapping by hand rather than letting it discover one.

A five-minute checklist

1. 1

   Get the exact message out of your provider

   missing or invalid Bearer token and invalid SCIM token send you to completely different sections above. 500 sends you to the filter section. Do not start from the status code.

2. 2

   Confirm the base URL

   /api/v1/scim/v2. No organisation in it. If your provider appended a tenant identifier because every other integration it does needs one, remove it.

3. 3

   Confirm the auth type is OAuth bearer token, and the scheme word is capitalised

   That covers the two most common causes between them.

4. 4

   Check the token list for a revoked row with the same prefix

   Revoked tokens are retained deliberately, so an auditor can see that a credential existed and when it stopped. That also makes them easy to recognise as the cause.

5. 5

   Mint a fresh token and paste it whole, including the prefix

   Faster than diagnosing a truncation. Then revoke the old one once the feed is healthy.

One token per connected system, named after the system that holds it. Revoking the Workday feed should not break the Entra ID feed, and the history should tell you which system did what. The rest of the setup is in SCIM inbound provisioning.