SCIM Admin API

​

Endpoints at a glance

​

Authentication

​

Inspect SCIM configuration

GET /api/config/scim/config

{
  "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

POST /api/config/scim/tokens/rotate

{
  "success": true,
  "data": {
    "token": "scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "rotated_at": "2026-04-25T14:02:11Z"
  }
}

​

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

POST /api/config/scim/tokens/revoke

• 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

PUT /api/config/scim/group-role-mapping
Content-Type: application/json

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

{ "group_role_mapping": {} }

​

Mapping key choice

• 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.

​

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 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 for the full set of guarded surfaces.

​

Manual validation steps