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

> Manage SCIM bearer tokens and group-to-role mappings for inbound provisioning.

The SCIM admin API lives under `/api/config/scim` on the same Genesis host that
serves your dashboard. Calls require an authenticated Genesis admin session
with the `ACCESS_CONFIG_PANEL` permission. These endpoints are how you generate
and rotate SCIM bearer tokens, configure group-to-role mappings, and inspect
SCIM configuration state.

For the SCIM provisioning surface used by IdPs (`/scim/v2`), see the
[SCIM API Reference](/docs/Setup/SCIM-API-Reference).

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

## Endpoints at a glance

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/api/config/scim/config` | Inspect tenant metadata, current group-to-role mapping, admission mode, and the count and state of persisted tokens. Plaintext bearer tokens are never returned. |
| `POST` | `/api/config/scim/tokens/rotate` | Create a new persisted SCIM bearer token. The plaintext token is returned **once**. |
| `POST` | `/api/config/scim/tokens/revoke` | Revoke all persisted SCIM bearer tokens for the tenant. |
| `PUT` | `/api/config/scim/group-role-mapping` | Replace the tenant group-to-role mapping. |

<Warning>
  The plaintext bearer token is only returned in the response to
  `POST /api/config/scim/tokens/rotate`. Save it immediately. Genesis stores
  only a hash of the token after rotation.
</Warning>

## Authentication

Admin API calls authenticate the same way as other Genesis admin requests: an
authenticated admin session with the `ACCESS_CONFIG_PANEL` permission.

The SCIM bearer token returned by `tokens/rotate` is a separate credential
used **only** by IdPs against `/scim/v2`. SCIM bearer tokens cannot
authenticate any other Genesis API.

## Inspect SCIM configuration

```bash theme={null}
GET /api/config/scim/config
```

Returns the tenant identifier, effective group-to-role mapping, current
admission mode (whether SCIM-only sign-in is enforced), the number of
persisted tokens, and the last rotation timestamp.

```json theme={null}
{
  "success": true,
  "data": {
    "tenant_id": "default",
    "group_role_mapping": {
      "company-admins": "admin",
      "company-users": "user"
    },
    "require_provisioned_users": false,
    "tokens": {
      "count": 1,
      "last_rotated_at": "2026-04-25T14:02:11Z"
    }
  }
}
```

## Rotate a bearer token

```bash theme={null}
POST /api/config/scim/tokens/rotate
```

Returns a freshly generated plaintext token. Save it immediately and configure
your IdP with it before the request output is gone.

```json theme={null}
{
  "success": true,
  "data": {
    "token": "scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "rotated_at": "2026-04-25T14:02:11Z"
  }
}
```

Rotating creates a new active token. If your deployment was previously running
on an environment-variable token (`GENESIS_SCIM_BEARER_TOKEN`), the persisted
token returned here takes precedence after rotation.

### Token rotation cadence

* Rotate before initial production rollout, after staff turnover or off-boarding,
  and immediately on suspected disclosure or incident response.
* Schedule periodic rotations (for example, quarterly) per your security
  policy.
* After rotation, update the IdP secret value before the IdP attempts its next
  push.

## Revoke tokens

```bash theme={null}
POST /api/config/scim/tokens/revoke
```

Revokes all persisted SCIM bearer tokens for the tenant. After revocation the
IdP will receive a SCIM-shaped `401`/`403` until a new token is rotated and
configured on the IdP side.

Use revocation to:

* Cut off a leaked token immediately.
* Decommission a SCIM integration without uninstalling Genesis.
* Force the IdP off a stale credential before a new rotation is staged.

## Configure the group-to-role mapping

```bash theme={null}
PUT /api/config/scim/group-role-mapping
Content-Type: application/json

{
  "group_role_mapping": {
    "company-admins": "admin",
    "company-users": "user"
  }
}
```

The request body **replaces** the entire mapping for the tenant. To remove a
mapping, omit it from the body and re-PUT the rest. To clear the mapping,
PUT an empty object:

```json theme={null}
{ "group_role_mapping": {} }
```

### Mapping key choice

Map by whatever the IdP sends as the SCIM group identifier:

* If your IdP sends a human-readable `displayName` (Okta, Entra ID with display
  names, OneLogin), use that as the key.
* If your IdP sends opaque identifiers in `externalId` (some Entra ID and
  AWS-sourced flows), use the externalId value as the key.

You can mix both styles in the same mapping if different IdP groups send
different identifier shapes.

### Mapping change effects

* Mapping changes take effect on the next SCIM Group operation that touches an
  affected group.
* Removing a mapping for a previously mapped group does **not** revoke role
  membership retroactively. To revoke, push an updated SCIM Group with the
  desired members (or remove the user from the group in the IdP), or remove
  the user from the group on the IdP side.
* Changing a mapping target role (for example, `company-users: user` →
  `company-users: analyst`) becomes effective the next time the IdP pushes
  that group. Re-pushing the group from the IdP applies the new role to all
  members.

## Permissions and audit

* All admin endpoints require the `ACCESS_CONFIG_PANEL` permission.
* Token rotation, token revocation, and mapping replacement write rows to the
  `SCIM_AUDIT_LOG` table. See [SCIM Monitoring](/docs/Setup/SCIM-Monitoring)
  for example audit queries and SIEM export guidance.
* Manual user-role edits for SCIM-managed users are blocked through the UI,
  the role API, and admin tools. See
  [SCIM Security](/docs/Setup/SCIM-Security) for the full set of guarded
  surfaces.

## Manual validation steps

Use these steps in a non-production deployment to confirm admin API behavior
end-to-end:

<Steps>
  <Step title="Inspect">
    Call `GET /api/config/scim/config`. Confirm the tenant id and the
    expected group-to-role mapping are returned and that no plaintext token is
    present.
  </Step>

  <Step title="Rotate">
    Call `POST /api/config/scim/tokens/rotate`. Save the returned token.
  </Step>

  <Step title="Use the new token">
    Call `GET /scim/v2/ServiceProviderConfig` with the new token in the
    `Authorization: Bearer ...` header. Confirm a `200` SCIM
    `ServiceProviderConfig` response.
  </Step>

  <Step title="Revoke">
    Call `POST /api/config/scim/tokens/revoke`. Re-call
    `GET /scim/v2/ServiceProviderConfig` with the same bearer token and
    confirm a SCIM-shaped `401`/`403`.
  </Step>

  <Step title="Replace mapping">
    Call `PUT /api/config/scim/group-role-mapping` with a new mapping.
    Re-fetch `GET /api/config/scim/config` and confirm the mapping is updated.
  </Step>
</Steps>