SCIM API Reference

This page documents the SCIM 2.0 service-provider endpoints exposed by Genesis at /scim/v2. These are the endpoints your IdP calls. For the admin endpoints used to manage SCIM tokens and group-to-role mappings, see the SCIM Admin API. Databricks App behavior: API reference.

Base URL

https://<genesis-host>/scim/v2

Authentication

All /scim/v2 requests require a SCIM bearer token in the Authorization header:

Authorization: Bearer <SCIM token>

Generate the token through POST /api/config/scim/tokens/rotate.

Content type

Request bodies must be application/json or application/scim+json. Responses are returned as application/scim+json.

Metadata endpoints

Method	Path	Purpose
`GET`	`/ServiceProviderConfig`	Service-provider metadata, including supported features (PATCH supported, ETag not advertised, Bulk not supported).
`GET`	`/ResourceTypes`	Lists supported SCIM resource types (`User`, `Group`).
`GET`	`/Schemas`	Lists supported SCIM core schemas and the SCIM Enterprise User extension.

User endpoints

Method	Path	Purpose
`GET`	`/Users`	List or filter users. Supports `filter=userName eq "..."`, `startIndex`, and `count`.
`POST`	`/Users`	Create or upsert a SCIM user.
`GET`	`/Users/{id}`	Fetch one user.
`PUT`	`/Users/{id}`	Replace one user.
`PATCH`	`/Users/{id}`	Patch one user (RFC 7644 PATCH operations, including `active=false`).
`DELETE`	`/Users/{id}`	Soft-deactivate the user (sets `active=false`). Genesis never hard-deletes users via SCIM.

Genesis accepts title as a top-level SCIM user attribute. For enterprise profile data, Genesis accepts the standard Enterprise User extension urn:ietf:params:scim:schemas:extension:enterprise:2.0:User and persists employeeNumber, division, and department. For backward compatibility, create and replace payloads also accept top-level employeeNumber, division, and department. If both top-level and extension values are provided, Genesis uses the top-level values.

User payload example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "externalId": "idp-user-123",
  "userName": "[email protected]",
  "active": true,
  "displayName": "Alice Example",
  "name": {
    "givenName": "Alice",
    "familyName": "Example"
  },
  "title": "Senior Solutions Engineer",
  "emails": [
    { "value": "[email protected]", "primary": true }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "E-1001",
    "division": "Client Success",
    "department": "Solutions Engineering"
  }
}

Genesis persists these core User fields when present: displayName, name.givenName, name.familyName, emails, active, externalId, and title. Genesis also persists employeeNumber, division, and department from the SCIM Enterprise User extension namespace shown above. User detail and list responses omit optional properties whose value is unset instead of returning them as null. When enterprise profile data is present, Genesis includes the Enterprise User schema in schemas and returns those values under the Enterprise User extension object.

User PATCH example: deactivate

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

Filter and pagination

GET /scim/v2/Users supports:

filter=userName eq "<email>"
startIndex (1-based, defaults to 1)
count (defaults to 100)

Example:

GET /scim/v2/Users?filter=userName eq "[email protected]"&startIndex=1&count=10

The response is a SCIM ListResponse:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "itemsPerPage": 1,
  "startIndex": 1,
  "Resources": [
    { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "...", "userName": "[email protected]" }
  ]
}

Group endpoints

Method	Path	Purpose
`GET`	`/Groups`	List or filter groups.
`POST`	`/Groups`	Create a group or replace a group’s membership snapshot.
`GET`	`/Groups/{id}`	Fetch one group.
`PUT`	`/Groups/{id}`	Replace one group, including its full member list.
`PATCH`	`/Groups/{id}`	Patch one group (add or remove members, change displayName).
`DELETE`	`/Groups/{id}`	Remove role memberships granted by this group. Does not deactivate users.

Group payload example

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "company-users",
  "displayName": "company-users",
  "members": [
    { "value": "[email protected]", "display": "Alice Example" }
  ]
}

Group PATCH example: add and remove members

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{ "value": "[email protected]", "display": "Bob Example" }]
    },
    {
      "op": "remove",
      "path": "members[value eq \"[email protected]\"]"
    }
  ]
}

Group membership PATCH operations apply transactionally to the group. If the group is mapped in the Genesis group-to-role mapping, adds and removes immediately update the corresponding Genesis role assignments. Members removed from a group keep all of their other roles and remain active.

Error format

Genesis returns SCIM-shaped error payloads with proper HTTP status codes, scimType, and detail:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "400",
  "scimType": "invalidValue",
  "detail": "Group key is not present in the configured group-to-role mapping."
}

Status	Common causes
`400`	Invalid SCIM payload, unsupported operation, or unmapped group.
`401`	Missing `Authorization` header.
`403`	Invalid or revoked SCIM bearer token, or token belongs to a different tenant.
`404`	Resource id not found.
`429`	Per-token rate limit exceeded.
`500`	Internal Genesis error. Inspect server logs and `SCIM_AUDIT_LOG`.

Service-provider configuration

GET /scim/v2/ServiceProviderConfig returns the supported features:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "patch":          { "supported": true },
  "bulk":           { "supported": false, "maxOperations": 0, "maxPayloadSize": 0 },
  "filter":         { "supported": true,  "maxResults": 1000 },
  "changePassword": { "supported": false },
  "sort":           { "supported": false },
  "etag":           { "supported": false },
  "authenticationSchemes": [
    {
      "type":        "oauthbearertoken",
      "name":        "Bearer Token",
      "description": "SCIM bearer token",
      "primary":     true
    }
  ]
}

Limits

Filter: maxResults is 1000.
Pagination: count defaults to 100. Use startIndex and count to page through large result sets.
Bulk: not supported.
ETag / If-Match: not supported in this release. Genesis returns weak version metadata in the resource meta.version field but does not enforce optimistic concurrency.
Rate limit: per-token, default 600 requests per minute (configurable via GENESIS_SCIM_RATE_LIMIT_PER_MINUTE). For multi-replica deployments, enforce strict global limits at ingress / WAF / API gateway / a shared limiter.

SCIM Inbound Provisioning — overview
SCIM Admin API — token and mapping management
Okta SCIM Setup Guide — screenshot-backed Okta setup
SCIM IdP Setup Guides — Okta, Entra ID, OneLogin, AWS-sourced
SCIM Pilot Runbook — validation steps and conformance harness

Getting Started

Getting to Know Genesis

Creating A Mission

User Guide

Blueprint

Genesis Data Agents

Genesis Prover

Genesis Apps

Genesis REST API

Genesis Agent Security Controls

Genesis Data Agent's Toolkit

Setup

Slack and Teams

Data Connections

Deployment Options

Base URL

Authentication

Content type

Metadata endpoints

User endpoints

User payload example

User PATCH example: deactivate

Group endpoints

Group payload example

Group PATCH example: add and remove members

Error format

Service-provider configuration

Limits

​Base URL

​Authentication

​Content type

​Metadata endpoints

​User endpoints

​User payload example

​User PATCH example: deactivate

​Filter and pagination

​Group endpoints

​Group payload example

​Group PATCH example: add and remove members

​Error format

​Service-provider configuration

​Limits

​Related pages

Base URL

Authentication

Content type

Metadata endpoints

User endpoints

User payload example

User PATCH example: deactivate

Filter and pagination

Group endpoints

Group payload example

Group PATCH example: add and remove members

Error format

Service-provider configuration

Limits

Related pages