Skip to main content

SCIM Overview

What is SCIM?​

SCIM, or System for Cross-domain Identity Management, is a standardized protocol designed to automate the management of user identities across different systems. Developed in 2011, SCIM addresses the need for a unified approach to handle user data as businesses increasingly adopt cloud-based technologies.

For more information, visit the SCIM website.

Purpose of SCIM​

SCIM streamlines and secures user account management by automating tasks such as adding, updating, and removing users. This reduces the burden on IT departments and improves the user experience.

Benefits of SCIM​

  • Efficiency: Manages increasing numbers of user accounts efficiently and handles provisioning and permissions without manual intervention.
  • Consistency: Standardizes how user data is stored and communicated, ensuring information remains consistent across applications.
  • Error Reduction: Minimizes the risk of mistakes from manual data entry or custom integrations.
  • Security: Reduces risks by ensuring users don't need multiple passwords and keeps data synchronized, aiding in policy enforcement.

How SCIM Works​

SCIM operates over REST and JSON protocols, involving:

  • Identity Providers (IdPs): Systems like Okta that maintain comprehensive directories of user identities.
  • Service Providers (SPs): Applications such as Slack or Box that require user data from IdPs.

When changes occur in the IdP (e.g., user profiles created or updated), these changes are automatically synced to the SP, keeping user information up-to-date and providing seamless access to applications and resources.

Multi-tenant SCIM​

The SCIM server supports a tenant-aware URL form so a single Permit environment can back multiple isolated customer tenants. Two base URL shapes are supported — the SCIM client (Okta, Entra) appends the resource path (/Users, /Groups, etc.) to whichever base URL you configure:

  • Legacy (single-tenant) base URL: https://scim.permit.io/scim/v2/{permit_project_id}/{permit_env_id}
    • Resource endpoints: .../Users, .../Groups.
    • All role assignments land in the default tenant. Existing integrations continue to work unchanged.
  • Tenant-aware base URL: https://scim.permit.io/scim/v2/{permit_project_id}/{permit_env_id}/v2/{tenant_id}
    • Resource endpoints: .../Users, .../Groups.
    • The {tenant_id} segment is required — there is no tenant-less /v2/Users. SCIM clients bake the tenant into their endpoint configuration, so each tenant points its IdP at its own base URL.

Replace {permit_project_id} and {permit_env_id} with your Permit project ID/Key and environment ID/Key respectively, and {tenant_id} with the target Permit tenant key.

EU users replace the scim.permit.io host with scim.eu-central-1.permit.io in either shape — e.g. https://scim.eu-central-1.permit.io/scim/v2/{permit_project_id}/{permit_env_id} (legacy) or https://scim.eu-central-1.permit.io/scim/v2/{permit_project_id}/{permit_env_id}/v2/{tenant_id} (tenant-aware).

note

The second /v2/ segment in the tenant-aware URL is a routing prefix that selects the multi-tenant SCIM API; it is not a SCIM protocol version. The SCIM 2.0 protocol version is the earlier /scim/v2/ segment.

{tenant_id} must match [A-Za-z0-9_-]{1,64} (1–64 chars: alphanumerics, underscore, hyphen). Invalid values return a 404 at the routing layer before any handler runs.

How users, groups, and tenants relate​

  • Users are environment-scoped. A SCIM User created via any tenant URL is provisioned once in the Permit environment. The {tenant_id} segment is accepted in the URL but does not partition users — userName remains globally unique within the environment.
  • Groups (roles) are environment-scoped definitions. A Group with displayName: "Engineering" resolves to a single role in the environment. If two tenants both create a Group with the same displayName, they share the same underlying role definition; the second POST /Groups reuses the existing role rather than failing. Matching is by the normalized role key (non-alphanumeric characters other than - and _ are stripped), not the raw displayName — so two different display names that normalize to the same key (e.g. Eng Team and EngTeam both → EngTeam) are rejected rather than merged.
  • Group membership (role assignment) is tenant-scoped. Adding a user to a Group via /v2/{tenant_id}/Groups/... grants that user the role within that tenant. The same user can hold the Engineering role in tenant acme and not in tenant globex. Membership in one tenant has no effect on membership in another.

This matches Permit's data model: roles are defined per environment, and assignments carry a tenant. It avoids duplicating role definitions per tenant while keeping each tenant's user-to-role bindings fully independent.

Choosing between the two URLs​

  • Use the legacy URL for existing single-tenant integrations or when all users share one logical tenant.
  • Use the tenant-aware URL when one Permit environment serves multiple customers and each must have its own isolated set of role assignments. Provision one SCIM connection per tenant in your IdP, each pointing at its own /v2/{tenant_id}/... endpoint.
caution

The target Permit tenant must already exist before you provision the SCIM connection. The SCIM server validates the {tenant_id} format but does not create the tenant — it auto-creates missing users, but there is no equivalent tenant auto-creation. Pointing a SCIM client at a {tenant_id} that does not yet exist in the environment causes the role-assignment call to fail and surfaces as an error to your IdP.

Contents