Update SCIM_overview.mdx#627
Conversation
✅ Deploy Preview for permitio-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
Adds documentation to the SCIM Overview page describing how Permit’s SCIM endpoint behaves in multi-tenant setups, including tenant-aware URL shapes and the scoping rules for users, roles (groups), and role assignments.
Changes:
- Fixes a minor formatting/typography issue in the “Security” benefit bullet.
- Introduces a new “Multi-tenant SCIM” section explaining supported URL shapes and tenant scoping behavior.
- Adds guidance on choosing legacy vs tenant-aware SCIM endpoints.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| The SCIM server supports a tenant-aware URL form so a single Permit environment can back multiple isolated customer tenants. Two URL shapes are supported: | ||
|
|
||
| - **Legacy (single-tenant):** `/scim/v2/{PROJ_ID}/{ENV_ID}/Users` and `/Groups`. All role assignments land in the `default` tenant. Existing integrations continue to work unchanged. | ||
| - **Tenant-aware:** `/scim/v2/{PROJ_ID}/{ENV_ID}/v2/{TENANT_ID}/Users` and `/Groups`. The `TENANT_ID` segment is required — there is no tenant-less `/v2/Users`. SCIM clients (Okta, Entra) bake the tenant into their endpoint configuration, so each tenant points its IdP at its own URL. |
There was a problem hiding this comment.
Addressed in beeaa37 — the bullets now lead with a base URL ending at .../{permit_env_id} (legacy) or .../{tenant_id} (tenant-aware), with a leading sentence noting the SCIM client appends the resource path. Matches the convention in OKTA.mdx:36 and EntraID.mdx:55.
| - **Legacy (single-tenant):** `/scim/v2/{PROJ_ID}/{ENV_ID}/Users` and `/Groups`. All role assignments land in the `default` tenant. Existing integrations continue to work unchanged. | ||
| - **Tenant-aware:** `/scim/v2/{PROJ_ID}/{ENV_ID}/v2/{TENANT_ID}/Users` and `/Groups`. The `TENANT_ID` segment is required — there is no tenant-less `/v2/Users`. SCIM clients (Okta, Entra) bake the tenant into their endpoint configuration, so each tenant points its IdP at its own URL. |
There was a problem hiding this comment.
Addressed in beeaa37 — resource endpoints are now listed on their own bullet (.../Users, .../Groups) under each base URL, replacing the ambiguous "...Users and /Groups" phrasing.
| - **Legacy (single-tenant):** `/scim/v2/{PROJ_ID}/{ENV_ID}/Users` and `/Groups`. All role assignments land in the `default` tenant. Existing integrations continue to work unchanged. | ||
| - **Tenant-aware:** `/scim/v2/{PROJ_ID}/{ENV_ID}/v2/{TENANT_ID}/Users` and `/Groups`. The `TENANT_ID` segment is required — there is no tenant-less `/v2/Users`. SCIM clients (Okta, Entra) bake the tenant into their endpoint configuration, so each tenant points its IdP at its own URL. |
There was a problem hiding this comment.
Addressed in beeaa37 — {PROJ_ID}/{ENV_ID} → {permit_project_id}/{permit_env_id} to match OKTA.mdx and EntraID.mdx. Also lowercased TENANT_ID → {tenant_id} for placeholder-style consistency, and added the same "Replace … with …" mapping line that the sibling docs use.
| The SCIM server supports a tenant-aware URL form so a single Permit environment can back multiple isolated customer tenants. Two URL shapes are supported: | ||
|
|
||
| - **Legacy (single-tenant):** `/scim/v2/{PROJ_ID}/{ENV_ID}/Users` and `/Groups`. All role assignments land in the `default` tenant. Existing integrations continue to work unchanged. | ||
| - **Tenant-aware:** `/scim/v2/{PROJ_ID}/{ENV_ID}/v2/{TENANT_ID}/Users` and `/Groups`. The `TENANT_ID` segment is required — there is no tenant-less `/v2/Users`. SCIM clients (Okta, Entra) bake the tenant into their endpoint configuration, so each tenant points its IdP at its own URL. |
There was a problem hiding this comment.
Addressed in beeaa37 — added a :::note callout explicitly stating that the second /v2/ is the multi-tenant routing prefix and not a SCIM protocol version. The SCIM 2.0 protocol version is the earlier /scim/v2/ segment. Kept the URL literal since that's the actual API path.
dshoen619
requested review from
EliMoshkovich,
dshoen619 and
gemanor
and removed request for
dshoen619
Reframe URL examples as base URLs with resource paths appended by the
SCIM client, align placeholder names with sibling Okta/Entra docs
({permit_project_id}, {permit_env_id}, {tenant_id}), and clarify that
the second /v2/ segment is the multi-tenant routing prefix rather than
a SCIM protocol version.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
No description provided.