diff --git a/docs/src/understand/single-sign-on/understand/main.md b/docs/src/understand/single-sign-on/understand/main.md
index 8f17668899b..3df00226f30 100644
--- a/docs/src/understand/single-sign-on/understand/main.md
+++ b/docs/src/understand/single-sign-on/understand/main.md
@@ -460,8 +460,8 @@ If you already have a SCIM token and want to associate it with a SAML
 IdP, delete the SCIM token and create a new one.  The user accounts
 provisioned with that token will remain unaffected.
 
-If you do not provide a SAML IdP, the behavior differes based on the
-version you use:
+If you do not provide a SAML IdP when creating it, the behavior
+differs based on the version you use:
 
 **V6 and below:** If there is a unique IdP registered with your team,
 associate implicitly.  Otherwise, do not associate.
diff --git a/libs/wire-api/src/Wire/API/User/IdentityProvider.hs b/libs/wire-api/src/Wire/API/User/IdentityProvider.hs
index 7283333f7a2..110696a925e 100644
--- a/libs/wire-api/src/Wire/API/User/IdentityProvider.hs
+++ b/libs/wire-api/src/Wire/API/User/IdentityProvider.hs
@@ -49,6 +49,7 @@ import Wire.Arbitrary (Arbitrary, GenericUniform (GenericUniform))
 -- | The identity provider type used in Spar.
 type IdP = IdPConfig WireIdP
 
+-- | Unique human-readable IdP name.
 newtype IdPHandle = IdPHandle {unIdPHandle :: Text}
   deriving (Eq, Ord, Show, FromJSON, ToJSON, ToSchema, Arbitrary, Generic)
 
diff --git a/services/spar/src/Spar/API.hs b/services/spar/src/Spar/API.hs
index c4da715bb54..2a59a3cc6c3 100644
--- a/services/spar/src/Spar/API.hs
+++ b/services/spar/src/Spar/API.hs
@@ -491,17 +491,14 @@ idpCreate zusr (IdPMetadataValue raw xml) = idpCreateXML zusr raw xml
 
 -- | We generate a new UUID for each IdP used as IdPConfig's path, thereby ensuring uniqueness.
 --
--- NOTE(mangoiv): currently registering an IdP and scim token works as follows:
--- - an owner creates a team with some teamId
--- - the owner registers and IdP
--- - the owner registers a scim token and passes the idp id along to associate
---   the scim token with the IdP
+-- The human-readable name argument `mHandle` is guaranteed to be unique for historical
+-- reasons.  At some point, we wanted to use it to refer to IdPs in the backend API.  The new
+-- idea is to use the IdP ID instead, and use names only for UI purposes (`ES branch` is
+-- easier to remember than `6a410704-b147-11ef-9cb0-33193c475ba4`).
 --
--- This doesn't support some flows we may want to support, like: (1) register
--- a scim token and then associate an IdP with it; (2) have scim token and
--- create an idp that is *not* associated with it; ...
---
--- Related internal docs: https://wearezeta.atlassian.net/wiki/spaces/PAD/pages/1107001440/2024-03-27+scim+user+provisioning+and+saml2+sso+associating+scim+peers+and+saml2+idps
+-- Related docs:
+-- (on associating scim peers with idps) https://docs.wire.com/understand/single-sign-on/understand/main.html#associating-scim-tokens-with-saml-idps-for-authentication
+-- (internal) https://wearezeta.atlassian.net/wiki/spaces/PAD/pages/1107001440/2024-03-27+scim+user+provisioning+and+saml2+sso+associating+scim+peers+and+saml2+idps
 idpCreateXML ::
   ( Member Random r,
     Member (Logger String) r,
@@ -517,7 +514,7 @@ idpCreateXML ::
   SAML.IdPMetadata ->
   Maybe SAML.IdPId ->
   Maybe WireIdPAPIVersion ->
-  Maybe (Range 1 32 Text {- human-readable idp name -}) ->
+  Maybe (Range 1 32 Text) ->
   Sem r IdP
 idpCreateXML zusr rawIdpMetadata idpmeta mReplaces (fromMaybe defWireIdPAPIVersion -> apiversion) mHandle = withDebugLog "idpCreateXML" (Just . show . (^. SAML.idpId)) $ do
   teamid <- Brig.getZUsrCheckPerm zusr CreateUpdateDeleteIdp
diff --git a/services/spar/src/Spar/Scim/Auth.hs b/services/spar/src/Spar/Scim/Auth.hs
index 1ed0c89a3ba..944c2afc3ff 100644
--- a/services/spar/src/Spar/Scim/Auth.hs
+++ b/services/spar/src/Spar/Scim/Auth.hs
@@ -160,9 +160,10 @@ createScimTokenV6 zusr createTok = do
     infoToV6 :: ScimTokenInfo -> ScimTokenInfoV6
     infoToV6 ScimTokenInfo {..} = ScimTokenInfoV6 {..}
 
--- | > docs/reference/provisioning/scim-token.md {#RefScimTokenCreate}
+-- | Create a token for the user's team.
 --
--- Create a token for user's team.
+-- > docs/reference/provisioning/scim-token.md {#RefScimTokenCreate}
+-- > (on associating scim peers with idps) https://docs.wire.com/understand/single-sign-on/understand/main.html#associating-scim-tokens-with-saml-idps-for-authentication
 createScimToken ::
   forall r.
   ( Member Random r,