> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM API Reference

> Endpoint reference, request and response shapes, and error format for the Genesis SCIM 2.0 service-provider API.

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](/docs/Setup/SCIM-Admin-API).

Databricks App behavior: [API reference](/docs/Genesis-API/API-Reference#scim-admin-configuration-endpoints).

## Base URL

```text theme={null}
https://<genesis-host>/scim/v2
```

## Authentication

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

```http theme={null}
Authorization: Bearer <SCIM token>
```

Generate the token through
[`POST /api/config/scim/tokens/rotate`](/docs/Setup/SCIM-Admin-API#rotate-a-bearer-token).

## 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

```json theme={null}
{
  "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": "alice@example.com",
  "active": true,
  "displayName": "Alice Example",
  "name": {
    "givenName": "Alice",
    "familyName": "Example"
  },
  "title": "Senior Solutions Engineer",
  "emails": [
    { "value": "alice@example.com", "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

```json theme={null}
{
  "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:

```text theme={null}
GET /scim/v2/Users?filter=userName eq "alice@example.com"&startIndex=1&count=10
```

The response is a SCIM `ListResponse`:

```json theme={null}
{
  "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": "alice@example.com" }
  ]
}
```

## 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

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "company-users",
  "displayName": "company-users",
  "members": [
    { "value": "alice@example.com", "display": "Alice Example" }
  ]
}
```

### Group PATCH example: add and remove members

```json theme={null}
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{ "value": "bob@example.com", "display": "Bob Example" }]
    },
    {
      "op": "remove",
      "path": "members[value eq \"alice@example.com\"]"
    }
  ]
}
```

Group membership PATCH operations apply transactionally to the group. If the
group is mapped in the Genesis [group-to-role mapping](/docs/Setup/SCIM-Admin-API#configure-the-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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

## Related pages

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