Document multi-tenant SCIM support in SCIM overview (#627)

* Update SCIM_overview.mdx

* Address Copilot review on SCIM multi-tenant URL examples

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>

* Address review: EU host, tenant pre-existence, normalized role key

Address Zeev's three inline review comments on PR #627:

- Add EU regional host (scim.eu-central-1.permit.io) variant for both
  legacy and tenant-aware base URLs, mirroring OKTA.mdx and EntraID.mdx.
- Note that the target Permit tenant must already exist; the SCIM server
  validates {tenant_id} format but does not auto-create tenants.
- Clarify that group reuse matches on the normalized role key, so two
  different display names that normalize to the same key are rejected
  rather than merged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: David Shoen <dbshoen@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Zeev Manilovich <zeevmoney@users.noreply.github.com>
Co-authored-by: dshoen619 <107557675+dshoen619@users.noreply.github.com>

Author: 4 people

docs/integrations/SCIM/SCIM_overview.mdx

@@ -18,7 +18,7 @@ SCIM streamlines and secures user account management by automating tasks such as
 - **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.
+- **Security:** Reduces risks by ensuring users don't need multiple passwords and keeps data synchronized, aiding in policy enforcement.
 
 ### How SCIM Works
 
@@ -27,3 +27,41 @@ SCIM operates over REST and JSON protocols, involving:
 - **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.
+:::