Skip to main content

SCIM Reference

This page documents the SCIM 2.0 behavior currently supported by Specmatic Insights for org admins and IdP administrators.

If you are integrating from Microsoft Entra, use the step-by-step guide:

For SCIM standards background:

Base URL and Endpoints​

SCIM base URL is tenant-scoped:

https://insights.specmatic.io/<orgId>/scim/v2

Core resource endpoints:

  • GET|POST /<orgId>/scim/v2/Users
  • GET|PUT|PATCH|DELETE /<orgId>/scim/v2/Users/{id}
  • GET|POST /<orgId>/scim/v2/Groups
  • GET|PUT|PATCH|DELETE /<orgId>/scim/v2/Groups/{id}

Metadata/discovery endpoints:

  • GET /<orgId>/scim/v2/ServiceProviderConfig
  • GET /<orgId>/scim/v2/ResourceTypes
  • GET /<orgId>/scim/v2/ResourceTypes/{id}
  • GET /<orgId>/scim/v2/Schemas
  • GET /<orgId>/scim/v2/Schemas/{id}

Not supported:

  • /<orgId>/scim/v2/Me returns 501 Not Implemented.
  • Bulk operations are not supported.
  • Sort is not supported.

Authentication​

Supported auth type:

  • Authorization: Bearer <SCIM token>

Where to get the token in Insights:

  1. Sign in as an org admin.
  2. Open Settings → Identity Access.
  3. Enable SCIM (if needed) and use Rotate Token to issue a token.
  4. Copy and store the one-time raw token securely.

Operator Notes: Enabling SCIM per Org​

Use this checklist when turning on SCIM for an organization:

  1. Open Settings → Identity Access.
  2. Set your identity provider protocol (SAML or OIDC) and Save Configuration.
  3. Enable SCIM provisioning and Save Configuration.
  4. Rotate the SCIM token and configure your IdP with:
    • Base URL: https://insights.specmatic.io/<orgId>/scim/v2
    • Header: Authorization: Bearer <SCIM token>
  5. Start provisioning from the IdP and verify user creation/update in Insights.

For predictable onboarding, set up identity in this order:

  1. Configure and validate SSO in Settings -> Identity Access.
  2. Enable SCIM and configure your IdP provisioning endpoint/token.
  3. Ensure relevant users and groups are syncing from IdP to Insights.
  4. Open Settings -> Collaborators -> SCIM Groups.
  5. Select synced groups and map them to an Insights role and identity type.

Mapping is applied per SCIM group in Collaborators using four actions:

  • Mark as User (Human)
  • Mark as Admin (Human)
  • Mark as User (Service account)
  • Mark as Admin (Service account)

These mappings determine the effective role and identity type hydrated into org memberships.

Expected Login Behavior When SCIM Is Enabled​

When SCIM is enabled for an org, Insights treats the org as SCIM-managed for user lifecycle:

  • SSO login is allowed only for users already provisioned in that org through SCIM.
  • SSO Just-in-Time (JIT) user creation is blocked for users not provisioned via SCIM.
  • Non-provisioned SSO sign-ins are denied with an authorization failure.

Operationally, provision users first (or provision and assign in scope), then ask users to sign in.

Capabilities​

Insights SCIM endpoint advertises and supports:

  • PATCH: supported
  • ETag/versioning: supported
  • Filtering: supported (maxResults = 100)
  • Change password: not supported
  • Sort: not supported
  • Bulk: not supported

Notes:

  • ETag is returned on User and Group resources.
  • Conditional update semantics (If-Match) are enforced by the SCIM integration path.

Pagination​

Pagination uses standard SCIM parameters:

  • startIndex (1-based)
  • count

Current behavior:

  • startIndex < 1 is normalized to 1.
  • count < 1 is normalized to 1.
  • Service provider config advertises filtered max results of 100.

Recommended client behavior:

  • Send count <= 100 for predictable interoperability with IdPs and validators.

Supported User Attributes​

Returned on GET/LIST​

  • id
  • externalId (when set)
  • userName
  • active
  • groups (direct memberships, including value, display, type, $ref)
  • meta.resourceType
  • meta.created
  • meta.lastModified
  • meta.version (ETag)

Accepted on POST/PUT​

  • id:
    • ignored/rejected on POST (client must not supply create id)
    • must match path id on PUT when supplied
  • externalId
  • userName (required)
  • active (defaults to true on create when omitted)

PATCH support for User​

Supported operations:

  • add, replace, remove

Supported paths:

  • active
  • userName
  • externalId
  • null path with object payload containing the above keys

Filter support for User list:

  • Attributes: id, externalId, userName, active
  • Comparator: eq
  • Logical nesting (and, or, not) is supported for supported attributes/operators.
  • Unsupported operators/attributes return 400 with SCIM invalidFilter.

Supported Group Attributes​

Returned on GET/LIST​

  • id
  • externalId (when set)
  • displayName
  • members (unless excluded via excludedAttributes=members on list)
  • meta.resourceType
  • meta.created
  • meta.lastModified
  • meta.version (ETag)

Accepted on POST/PUT​

  • id:
    • ignored/rejected on POST (client must not supply create id)
    • must match path id on PUT when supplied
  • externalId
  • displayName (required)
  • members (value references)

PATCH support for Group​

Supported operations:

  • add, replace, remove

Supported paths:

  • displayName
  • externalId
  • members
  • members[value eq "<memberId>"] (for targeted member remove)
  • null path with object payload containing supported keys

Filter support for Group list:

  • Attribute: displayName
  • Comparator: eq
  • Logical nesting (and, or, not) is supported for supported attributes/operators.
  • Unsupported operators/attributes return 400 with SCIM invalidFilter.

Group Mapping in Insights​

After groups are synced over SCIM, org admins can map each group to:

  • Insights role: User or Admin
  • Identity type: Human or Service account

Defaults for newly synced groups:

  • Role defaults to User.
  • Identity type defaults to Human.

These mappings are managed in Settings -> Collaborators -> SCIM Groups, not in IdP attribute mappings.

Practical Interoperability Notes​

  • Prefer SCIM-compliant clients that use discovery endpoints (ServiceProviderConfig, ResourceTypes, Schemas) before provisioning.
  • If your IdP supports both disable and delete semantics, Insights supports both:
    • deactivate via User PATCH active=false
    • hard delete via User DELETE
  • For duplicate create attempts (POST /Users with conflicting unique identifiers), Insights returns conflict semantics (409).