SCIM Provisioning

Beta: This feature is currently available to beta users only. Contact help@obvious.ai to request access.

This guide covers how to automate user and group provisioning in Obvious using SCIM 2.0 — including generating a SCIM token, configuring your identity provider, and setting up group-to-role mappings.

SCIM (System for Cross-domain Identity Management) lets your identity provider — Okta, Azure AD, or any SCIM 2.0-compatible IdP — automatically create, update, and deactivate Obvious workspace members. Once configured, you manage access in one place and Obvious stays in sync.

Prerequisites

Workspace owner or admin role
An identity provider that supports SCIM 2.0 (Okta, Azure AD, or equivalent)

Get your SCIM credentials

Before configuring your IdP, you need a SCIM bearer token and your workspace's SCIM base URL.

Open Settings → SCIM Provisioning.
Click Generate token.
Copy the token immediately — it's shown only once and can't be retrieved after you close this dialog. Store it in a secure location such as a password manager or secrets vault.

Your SCIM base URL is:

https://api.obvious.ai/scim/v2

You'll enter both the base URL and the bearer token into your IdP's SCIM configuration.

Note: Only workspace owners and admins can generate, rotate, or revoke SCIM tokens. If you don't see SCIM Provisioning in the sidebar, check your workspace role.

Configure your IdP

Okta

The exact steps to configure SCIM in Okta vary depending on your Okta version and app setup — refer to Okta's SCIM provisioning documentation for current instructions. In general, you'll need to:

Open or create your Obvious app in the Okta Admin console
Navigate to the app's Provisioning settings and enable API integration
Enter the SCIM connector base URL: https://api.obvious.ai/scim/v2
Set the Unique identifier field to userName
Enter your API Token (the SCIM bearer token you generated above)
Test the API credentials to verify the connection
Enable the provisioning operations you want Okta to manage: Create Users, Update User Attributes, Deactivate Users, and Push Groups

Azure Active Directory

The exact steps to configure SCIM in Azure AD vary depending on your tenant configuration — refer to Microsoft's Entra ID SCIM documentation for current instructions. In general, you'll need to:

Open or create your Obvious app in Enterprise applications
Navigate to Provisioning and set Provisioning Mode to Automatic
Under Admin Credentials, enter:
- Tenant URL: https://api.obvious.ai/scim/v2
- Secret Token: your SCIM bearer token
Test the connection to confirm Azure AD can reach the endpoint
Under Mappings, verify that userPrincipalName is mapped to userName — this is the default and is correct
Set Provisioning Status to On

Note: Azure AD sends a GET /scim/v2/ServiceProviderConfig request during setup to auto-detect supported capabilities. Obvious responds with its full capability advertisement, so Azure should configure itself correctly.

How user provisioning works

When your IdP provisions a user, Obvious creates a new workspace member with their email address as the username. If the user already exists in Obvious (matched by email), their workspace membership is updated rather than duplicated.

Supported user attributes

SCIM attribute	Obvious field
userName	Primary email / username
name.givenName	First name
name.familyName	Last name
displayName	Display name
emails[primary]	Primary email (takes precedence over userName if present)
active	Active / suspended state
externalId	IdP-side identifier (stored for correlation)

Deprovisioning

When your IdP deprovisions a user (sets active: false or sends a DELETE request), Obvious suspends the user's account and removes their workspace membership. Their sessions are revoked immediately. All their projects and data remain intact — the user is simply no longer able to access the workspace.

How group provisioning works

SCIM groups in Obvious map to Teams. When your IdP syncs a group:

A new Team is created in the workspace with the group's displayName.
Members are added or removed as the IdP updates group membership.
If a user is removed from a group but is still in other groups, their membership in those teams is preserved.
Deleting a group via SCIM soft-deletes the corresponding Team and removes all its members.

Teams created via SCIM are marked as SCIM-managed. You can view them in your workspace like any other Team.

Group-to-role mappings

By default, SCIM-provisioned users get the workspace_member role. You can map specific IdP groups to workspace roles so that group membership automatically controls access level.

The three mappable roles are:

Role	Access level
workspace_admin	Full workspace administration
workspace_member	Standard member access
workspace_guest	View-only access

How role assignment works:

When a user belongs to multiple groups with role mappings, Obvious assigns the highest-privilege role. For example, if a user is in both a workspace_guest-mapped group and a workspace_member-mapped group, they receive workspace_member.

Note: workspace_owner can never be assigned via SCIM. Manually assigned workspace roles are also preserved — SCIM role mappings only apply to users whose current role is managed by SCIM.

To retrieve current role mappings:

GET /workspaces/{workspaceId}/scim/role-mappings

Returns the active mappings array and a scimEnabled flag indicating whether SCIM is configured for the workspace. If no mappings have been set yet, mappings is an empty array.

To configure role mappings, replace the mappings array via the API:

PUT /workspaces/{workspaceId}/scim/role-mappings

Request body:

{
  "mappings": [
    {
      "groupExternalId": "00g1ab2cd3ef",
      "displayName": "Obvious Admins",
      "role": "workspace_admin"
    },
    {
      "groupExternalId": "00g9xy8wv7uv",
      "displayName": "Obvious Guests",
      "role": "workspace_guest"
    }
  ]
}

groupExternalId is the IdP's internal group identifier (visible in Okta under Directory → Groups → {Group} → General as the Object ID, or in Azure AD as the group's Object ID).

The PUT endpoint replaces all mappings atomically — partial updates aren't supported. Two constraints apply:

Maximum 500 mappings per workspace.
Each group can appear only once — duplicate groupExternalId values are rejected to prevent ambiguous role resolution.

Sending an empty array ("mappings": []) clears all mappings.

Note: Role mappings require an active SCIM configuration. Generate a SCIM token first before updating mappings.

Supported endpoints

Obvious implements the SCIM 2.0 protocol (RFC 7643 / RFC 7644). Here's a summary of the endpoints your IdP will use:

Endpoint	Methods	Description
/scim/v2/Users	GET, POST	List users; provision a new user
/scim/v2/Users/:id	GET, PUT, PATCH, DELETE	Get, update, or deprovision a user
/scim/v2/Groups	GET, POST	List groups; create a group
/scim/v2/Groups/:id	GET, PUT, PATCH, DELETE	Get, update, or delete a group
/scim/v2/ServiceProviderConfig	GET	Capability advertisement for IdPs
/scim/v2/Schemas	GET	Attribute definitions
/scim/v2/ResourceTypes	GET	Endpoint/schema mappings

All endpoints require a valid SCIM bearer token in the Authorization: Bearer <token> header.

Supported capabilities:

PATCH operations (partial updates)
Filter support on list endpoints (userName, externalId, active, displayName)
Pagination via startIndex and count parameters
Up to 200 results per filtered response

Bulk operations, sort, and ETag/conditional requests aren't supported.

Rotate or revoke a SCIM token

To rotate a token (generates a new token and immediately invalidates the old one):

Open Settings → SCIM Provisioning.
Click Rotate token.
Copy the new token and update your IdP configuration with it before SCIM operations resume.

To revoke a token (disables SCIM access entirely):

Open Settings → SCIM Provisioning.
Click Revoke token.

After revocation, your IdP can no longer reach the SCIM endpoints. Existing workspace members are unaffected — only new sync operations stop.

Audit log

All SCIM activity is recorded in the workspace audit log. Logged events include user and group creation, updates, deletions, member additions and removals, and token lifecycle events (generated, rotated, revoked).

To review SCIM activity, open your workspace audit log and filter by the scim. event namespace.

Troubleshooting

IdP returns a 401 Unauthorized error

The SCIM bearer token is invalid or has been revoked. Generate a new token in Settings → SCIM Provisioning and update your IdP configuration.

Users aren't being provisioned

Check that:

The Obvious SCIM app in your IdP has provisioning enabled and the Create Users operation turned on.
The userName attribute is mapped to the user's email address.
The user is assigned to the Obvious app in your IdP.

Group membership changes aren't reflecting in Obvious

Confirm that Push Groups (Okta) or group provisioning (Azure AD) is enabled on the app. In Okta, verify that the group is explicitly pushed — groups must be linked to the app to sync.

Role mappings aren't being applied

Role mappings apply when group membership changes. If roles look wrong after configuring mappings:

Call GET /workspaces/{workspaceId}/scim/role-mappings to verify the mappings are stored correctly.
Confirm the groupExternalId values match the IdP's internal group IDs exactly.
Trigger a group sync from your IdP to force Obvious to recalculate roles.

SCIM-managed users can't be edited in Obvious

Users and groups created via SCIM are marked as SCIM-managed. Certain attributes (like email and name) can only be updated through your IdP to prevent configuration drift. Update the user in your IdP and allow the sync to propagate.

If you're still running into issues, contact help@obvious.ai with your workspace ID and a description of the problem.