docs: Document supported SCIM features and correct the deprovisioning and base URL guidance (#8221)

Author: khvn26

docs/docs/administration-and-security/access-control/scim.md

@@ -18,13 +18,28 @@ With SCIM, you can:
 
 - Create Flagsmith users ahead of their first login, so they already have the right group memberships and permissions
   waiting for them.
-- Remove users from your Flagsmith organisation when they are deprovisioned in your identity provider
+- Remove users from your Flagsmith organisation when they are deprovisioned in your identity provider.
 - Sync group membership so that adding or removing a user from a group in your identity provider is reflected in
   Flagsmith automatically.
 
-SCIM works alongside your existing SSO configuration. SSO handles authentication (how users log in), while SCIM handles
+SCIM works alongside your existing SSO configuration: SSO handles authentication (how users log in), while SCIM handles
 provisioning (which users and groups exist in Flagsmith, and who belongs to what).
 
+## Supported features
+
+Flagsmith's SCIM 2.0 API supports:
+
+- Creating users.
+- Deleting users. See [User lifecycle](#user-lifecycle) for what is and is not removed.
+- Pushing groups: create and update [permission groups](/administration-and-security/access-control/rbac#groups) and
+  their membership, and delete groups.
+- Filtering and pagination on the `/Users` and `/Groups` list endpoints.
+
+Flagsmith does not support:
+
+- Deactivating users through the `active` attribute. Use DELETE requests to deprovision users instead.
+- Profile sourcing, `/Me`, `/Bulk`, sorting, and ETag concurrency control.
+
 ## Prerequisites
 
 - Your Flagsmith organisation must have an active Enterprise licence.
@@ -35,9 +50,8 @@ provisioning (which users and groups exist in Flagsmith, and who belongs to what
 
 :::caution
 
-Flagsmith requires the SCIM `userName` attribute to be the user's email address. Requests with a `userName` that is not
-a valid email address are rejected with a 400 response. Ensure your identity provider is configured to send email
-addresses as SCIM usernames — for example, in Okta, set the application username format to "Email".
+Flagsmith requires the SCIM `userName` attribute to be the user's email address. Ensure your identity provider is
+configured to send email addresses as SCIM usernames.
 
 :::
 
@@ -48,13 +62,32 @@ When your identity provider provisions a user through SCIM:
 2. If the user already exists (matched by email, case-insensitive), they are added to the organisation if they are not
    already a member.
 
-When your identity provider deprovisions a user (sets `active` to `false` or sends a DELETE request):
+When your identity provider deprovisions a user by sending a DELETE request:
 
 1. The user is removed from the organisation in Flagsmith. This also removes all their project and environment
    permissions within that organisation, and removes them from all
    [permission groups](/administration-and-security/access-control/rbac#groups) in that organisation.
 2. The user's data (audit log entries, change request history) is preserved.
 
+:::caution
+
+Deprovisioning is supported through DELETE requests only. Flagsmith does not act on the SCIM `active` attribute.
+
+:::
+
+### User attributes
+
+Flagsmith reads the following attributes from SCIM user requests:
+
+| Attribute         | Required | Maps to       |
+| ----------------- | -------- | ------------- |
+| `userName`        | Yes      | Email address |
+| `name.givenName`  | No       | First name    |
+| `name.familyName` | No       | Last name     |
+
+All other attributes are ignored. If your identity provider lets you choose which attributes to send, sending only the
+three above keeps your configuration simpler and avoids implying that Flagsmith stores data it does not.
+
 ## Group lifecycle
 
 SCIM groups map to Flagsmith [permission groups](/administration-and-security/access-control/rbac#groups) within the
@@ -93,10 +126,13 @@ shown only once and cannot be retrieved later. If you lose it, you can regenerat
 
 Add Flagsmith as a SCIM application in your identity provider. You will need:
 
-- **SCIM base URL**: `https://flagsmith.example.com/api/v1/scim/v2/`, replacing `flagsmith.example.com` with your
-  Flagsmith API domain. On Flagsmith SaaS, this is `https://api.flagsmith.com/api/v1/scim/v2/`.
+- **SCIM base URL**: `https://flagsmith.example.com/api/v1/scim/v2`, replacing `flagsmith.example.com` with your
+  Flagsmith API domain. On Flagsmith SaaS, this is `https://api.flagsmith.com/api/v1/scim/v2`.
 - **Bearer token**: the token you copied in the previous step.
 
+Both values are shown on the SCIM page in Flagsmith, so you can copy them directly rather than assembling the URL by
+hand.
+
 The exact steps depend on your identity provider. See the guides below for common providers.
 
 ### 3. Assign users and groups
@@ -116,29 +152,32 @@ You can view and manage SCIM configurations from **Organisation Settings** > **S
 
 :::note
 
-These guides were last verified in May 2026. If your identity provider's UI has changed, refer to their documentation
+These guides were last verified in July 2026. If your identity provider's UI has changed, refer to their documentation
 for the most up-to-date steps.
 
 :::
 
 ### Okta
 
-:::note
-
-We're working with Okta to enable SCIM for our Flagsmith OIN application. We'll update the docs as soon as we confirm it's working.
-
-:::
+These steps are for the Flagsmith application from the Okta Integration Network catalogue.
 
+1. Get your SCIM bearer token as described under [Setup](#1-create-a-scim-configuration).
 1. Go to the "Applications" page and open the Flagsmith application.
-2. Go to the "General" tab and click "Edit" under "App Settings".
-3. Enable "Provisioning" and click "Save".
-4. A new "Provisioning" tab will appear. Open it and click "Edit" under "SCIM Connection".
-5. Set the SCIM connector base URL to your Flagsmith SCIM base URL.
-6. Set the unique identifier field to `email`.
-7. Under "Supported provisioning actions", enable: Push New Users, Push Profile Updates, and Push Groups.
-8. Set the authentication mode to "HTTP Header" and paste your SCIM bearer token.
-9. Click "Test Connector Configuration" to verify the connection, then save.
-10. Still on the "Provisioning" tab, under "To App", enable: Create Users, Update User Attributes, and Deactivate Users.
+1. On the "Sign On" tab, under "Advanced Sign-on Settings", set API Base URL to your Flagsmith API domain. On Flagsmith
+   SaaS this is `https://api.flagsmith.com`.
+1. Still on the "Sign On" tab, under "Credentials Details", set the application username format to "Email". Flagsmith
+   requires the SCIM `userName` to be a valid email address.
+1. Go to the "General" tab, click "Edit" under "App Settings", enable "Provisioning" and click "Save". A "Provisioning"
+   tab appears.
+1. On the "Provisioning" tab, select "Integration" and click "Edit". Tick "Enable API integration" and paste your SCIM
+   bearer token into **API Token**.
+1. Click "Test API Credentials" to verify the connection, then save.
+1. Select "To App" and click "Edit", then enable "Create Users" and "Update User Attributes".
+
+To deprovision a user, unassign them from the application in Okta. Okta sends a DELETE request and Flagsmith removes the
+user from your organisation.
+
+To sync groups, use the "Push Groups" tab to select the Okta groups you want to push to Flagsmith.
 
 ### Microsoft Entra ID (Azure AD)
 
@@ -169,14 +208,13 @@ All SCIM endpoints are under `/api/v1/scim/v2/` and require a valid SCIM bearer
 API supports filtering (e.g. `filter=userName eq "user@example.com"`) and pagination (`startIndex`, `count`) on list
 endpoints as defined by the SCIM 2.0 specification.
 
-
 ## Troubleshooting
 
 ### Users are not being provisioned
 
-- Verify the SCIM base URL ends with `/api/v1/scim/v2/` (including the trailing slash).
+- Verify the SCIM base URL in your identity provider matches the one shown in Flagsmith under **Organisation
+  Settings** > **SSO** > **SCIM**.
 - Verify the bearer token is correct. If in doubt, regenerate it.
-- Check that the user's email address is included in the SCIM request. Flagsmith requires an email to create a user.
 - Check that the SCIM `userName` attribute is the user's email address. Flagsmith rejects requests with a non-email
   `userName` with a 400 response.
 
@@ -194,5 +232,7 @@ endpoints as defined by the SCIM 2.0 specification.
 
 ### Deprovisioned users still appear in the organisation
 
-- Check that your identity provider is sending a PATCH request with `active` set to `false`, or a DELETE request, when
-  deprovisioning a user. Some identity providers require explicit configuration to send deprovisioning events.
+- Check that your identity provider is sending a DELETE request when deprovisioning a user. Flagsmith does not act on
+  the `active` attribute, so a PATCH request setting `active` to `false` does not remove the user — it returns a 501
+  response. In Okta, this means removing the user from the application rather than deactivating them.
+- Some identity providers require explicit configuration to send deprovisioning events.