SCIM API
A standard SCIM 2.0 surface (Users, Groups) that a customer's IdP can point at for directory sync.
SCIM (System for Cross-domain Identity Management, RFC 7643/7644) is a standard protocol — RealmSSO doesn't invent its own shape here, it implements the conventional /Users and /Groups resources so that Okta, Microsoft Entra ID, or any other SCIM-speaking IdP can be pointed at it directly. Routes are mounted at /api/scim/v2 on the deployed server origin — that full URL is what the customer registers in their IdP. There is no SCIM base-URL setting: no environment variable or chart value rewrites response locations or the path a customer must register. See SCIM Directory Sync for the customer-facing setup flow.
Authentication
Every /Users and /Groups request must carry Authorization: Bearer <token>. The two discovery routes at the bottom of this page — /ServiceProviderConfig and /Schemas — are deliberately unauthenticated, because a SCIM connector introspects them before it has been given a token. The token is per-account: RealmSSO hashes the presented token with SHA-256 and looks it up against ScimConfig.bearerTokenHash for an enabled config. A missing header, or a hash that matches no enabled ScimConfig, gets a SCIM-shaped 401:
| Field | Value |
|---|---|
| schemas | ["urn:ietf:params:scim:api:messages:2.0:Error"] |
| status | "401" |
| detail | "Missing or invalid Authorization header" / "Invalid SCIM token" |
Writes persist — and two of the three config flags default off
POST/PUT/PATCH/DELETE) stores a real ScimUser, ScimGroup, or ScimGroupMember row and records an observability event, and reads query those rows — GET /Users returns what has actually been pushed, and GET /Users/:id returns 404 only for an id that is not there. Whether a write also reaches the account's Keycloak realm depends on the ScimConfig flags, and only autoProvision defaults on: autoDeprovision and groupSync both default false, so a default install creates Keycloak users but does not deactivate them and does not mirror groups. See SCIM Directory Sync for the configuration model.Users
/api/scim/v2/UsersSupports filter, startIndex, and count (capped at 200) query parameters per the SCIM list convention, returned as a ListResponse.
/api/scim/v2/UsersBody is a standard SCIM User resource — userName (required), optional name, emails, active (defaults true), and externalId.
/api/scim/v2/Users/:id/api/scim/v2/Users/:idFull replacement of the user resource, as SCIM defines it.
/api/scim/v2/Users/:idAccepts a standard SCIM PatchOp body (Operations: [{ op, path, value }] with op one of add/remove/replace).
/api/scim/v2/Users/:idThe conventional SCIM way to deactivate a user; responds 204.
Groups
/api/scim/v2/Groups/api/scim/v2/GroupsBody is a SCIM Group resource — displayName (required), optional members and externalId.
/api/scim/v2/Groups/:id/api/scim/v2/Groups/:id/api/scim/v2/Groups/:id/api/scim/v2/Groups/:idDiscovery endpoints
/api/scim/v2/ServiceProviderConfigAdvertises SCIM capabilities to the customer's IdP: patch and filter are supported, bulk, changePassword, and sort are not, and the only authentication scheme listed is OAuth Bearer Token.
/api/scim/v2/SchemasReturns the core SCIM 2.0 User and Group schema definitions.
See API Overview for the shared error format used outside the SCIM-specific error responses above (e.g. 404 from the SCIM routes still uses the standard NotFoundError), and Accounts API for how a ScimConfig relates to an account.