docs: add blank authentication and user provisioning pages

[mintlify]

Adds three placeholder pages for content to be written manually:

• administration/authentication/single_sign_on.md — "Single Sign On", under Authentication & access
• administration/authentication/magic_link.md — "Magic Link", under Authentication & access
• administration/managing_users/automated_user_provisioning.md — "Automated User Provisioning", under Users & roles

Each page contains only its title. Extracted from #380 so this authentication work can proceed independently of the Kosli Capture page.

---

Generated by Mintlify Agent.

Requested by: graham@kosli.com via Slack
Mintlify session: slack_1782915660.508229_D0AM66349C1

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
kosli	🟢 Ready	View Preview	Sep 3, 2026, 8:26 AM

[claude]

Claude finished @gsavage's task in 3m 54s —— View job

---

Doc quality review

All three new pages are listed in config/navigation.json (core rule 2 ✓). No pages moved or deleted, so no config/redirects.json entry is needed. Every internal link resolves — including the two intra-page anchors (#roles-for-new-and-existing-users, #map-your-idp-groups-to-kosli-roles) — and all eight added images are referenced with root-relative paths and real alt text. gh pr checks isn't available to this run, so link validation here was done by resolving each target against the tree by hand.

Four findings are posted inline. One more, which falls outside the diff hunks so GitHub won't take an inline comment:

administration/managing_users/roles_in_kosli.md:25-26 — Improvement

The Permissions Matrix is the part of this page an admin consults to answer "am I allowed to do this?", and it still asserts unconditionally that Admin can Invite and remove users and Change user roles. Both become false for a SCIM-provisioned organization: automated_user_provisioning.md:10-12 sells the feature precisely on no longer inviting people one-by-one and on access being revoked automatically, and automated_user_provisioning.md:108 says provisioned users' roles can no longer be changed in Kosli at all.

The new <Note> at line 191 carves out the procedure further down the page, but a reader who reads the matrix and stops — the normal way a matrix is used — never sees it. Worth qualifying those two rows, or adding a line under the matrix pointing at the SCIM caveat.

Fix this →

Still open from earlier rounds

magic_link.md:16-30 has three untitled <Step> elements, so they render as bare numbers, while single_sign_on.md:20-44 and automated_user_provisioning.md:41-61 — added in this same PR — title every step. Raised twice before and not picked up; mentioning once more only because the two auth pages are now inconsistent with each other and with service_accounts.md:15.

---

3 Improvements, 2 Suggestions. Nothing blocks the merge: the naming, casing, image-embedding and SCIM/roles-contradiction issues from earlier rounds are all fixed at head, and the remaining findings are sequencing and cross-page consistency rather than wrong instructions.
· branch docs/auth-pages

[claude]

Improvement — subject–verb disagreement, and the sentence has no full stop. "Kosli then sends you an email … and ask you to check your inbox" should be "asks". This is the only one of the three <Step> bodies on the page that doesn't terminate.

Suggested change

	Kosli then sends you an email containing the link and ask you to check your inbox
	Kosli then sends you an email containing the link and asks you to check your inbox.

[claude]

Improvement — "setup" is the noun; the verb is "set up".

Suggested change

	Magic Link is a way of signing into Kosli without needing to setup [single sign-on](/administration/authentication/single_sign_on). When you want to sign in, Kosli emails you a link, and clicking that link signs you in.
	Magic Link is a way of signing into Kosli without needing to set up [single sign-on](/administration/authentication/single_sign_on). When you want to sign in, Kosli emails you a link, and clicking that link signs you in.

[claude]

Improvement — the two pages added here still name their own features three different ways.

• This page: Single Sign On in the title, headings and body.
• magic_link.md:7 links here as "[single sign-on]", and automated_user_provisioning.md:16 links here as "[single sign-on]" too — so both inbound links are labelled differently from the page they land on.
• magic_link.md is split against itself: Magic Link in the title and line 7, magic link in both ## headings and lines 11/17.

CLAUDE.md asks for sentence case in headings, and every sibling in this group uses an unquoted sentence-case title (api_authentication_methods.md, service_accounts.md:2, api_key_rotation.md). "Single sign-on" is also the conventional rendering.

Suggested change

	title: Single Sign On
	title: Single sign-on

If you go with this, the ## Enabling Single Sign On heading (line 9) and line 7 need the same treatment, as does Magic Link → Magic link on the magic link page — pick one form per feature and use it in the title, headings, prose and link text.

[claude]

Suggestion — the <Step> elements have no title, unlike every other <Steps> block in administration/. single_sign_on.md:20-44 in this same PR titles all four of its steps, and service_accounts.md:15-28 titles all four of its. Without titles these render as bare numbers, so a reader scanning the page gets no summary of the flow.

Suggested change

	<Steps>
	<Steps>
	<Step>

The other two would be something like title="Check your inbox" and title="Click the link".

[claude]

Improvement — subject–verb disagreement, and the sentence has no full stop. "Kosli then sends you an email … and ask you to check your inbox" should be "asks". This is the only one of the three <Step> bodies that doesn't terminate.

Suggested change

	Kosli then sends you an email containing the link and ask you to check your inbox
	Kosli then sends you an email containing the link and asks you to check your inbox.

[claude]

Improvement — "setup" is the noun; the verb is "set up".

Suggested change

	Magic Link is a way of signing into Kosli without needing to setup [single sign-on](/administration/authentication/single_sign_on). When you want to sign in, Kosli emails you a link, and clicking that link signs you in.
	Magic Link is a way of signing into Kosli without needing to set up [single sign-on](/administration/authentication/single_sign_on). When you want to sign in, Kosli emails you a link, and clicking that link signs you in.

[claude]

Improvement — the headings here are Title Case, and the two new pages name their own features inconsistently.

CLAUDE.md asks for sentence case for all headings; every sibling in this group uses an unquoted sentence-case title (api_authentication_methods.md:2 "API authentication methods", service_accounts.md:2 "Service accounts", api_key_rotation.md:2 "API key rotation"). Here the title, ## Enabling Single Sign On, and the body all use "Single Sign On".

The inconsistency is also visible to a reader following links:

• magic_link.md:7 and automated_user_provisioning.md:16 both link here with the text "single sign-on", so the link label never matches the page they land on.
• magic_link.md is split against itself: Magic Link in the title and lines 7/17, magic link in both ## headings and line 11.

Pick one rendering per feature and use it in the title, headings, prose and inbound link text.

Suggested change

	title: Single Sign On
	description: "Learn about configuring Single Sign On with Kosli"
	icon: "key"
	---
	Kosli supports signing-in using your identity provider, via Single Sign On (SSO).
	## Enabling Single Sign On
	title: Single sign-on
	description: "Learn about configuring single sign-on with Kosli."
	icon: "key"
	---
	Kosli supports signing in using your identity provider, via single sign-on (SSO).
	## Enabling single sign-on

[claude]

Suggestion — these <Step> elements have no title, unlike every other <Steps> block in administration/. single_sign_on.md:20-44 in this same PR titles all four of its steps, and service_accounts.md:15-28 titles all four of its. Untitled steps render as bare numbers, so a reader scanning the page gets no summary of the flow — and the two pages added together are inconsistent with each other.

Suggested change

	<Steps>
	<Steps>
	<Step>

The other two would be something like title="Check your inbox" and title="Click the link".

[claude]

Improvement — the Setup sequence ends by triggering a sync, but the mapping that makes the sync produce correct roles isn't a step in it.

### Map your IdP groups to Kosli roles (line 88) is a required, three-step procedure in a different wizard, and it sits 26 lines below this block under a section titled "Roles for new and existing users" — which reads as conceptual, not procedural. Step 3 links there for "how to map those groups to Kosli roles", but a reader working this <Steps> block top-to-bottom reaches "Trigger a provisioning cycle" without having saved any mapping.

That matters more here than in most procedures, because the page itself says the first sync is not reversible in the app: it "provisions every assigned user at once" (line 76) and afterwards "their roles can no longer be changed in Kosli" (line 108).

Either pull the group-mapping steps into this sequence before the trigger step, or make the dependency explicit here:

Suggested change

	<Step title="Trigger a provisioning cycle">
	<Step>
	Before triggering a sync, map each IdP group to its Kosli role — see
	[Map your IdP groups to Kosli roles](#map-your-idp-groups-to-kosli-roles). Users provisioned before the
	mapping is saved will not get the roles you intend.
	</Step>
	<Step>

Fix this →

[claude]

Improvement — on this page, "users" is defined to include service accounts, which makes this note say something you don't mean.

roles_in_kosli.md:8 sets a page-wide convention: "Wherever this page mentions a 'user', read it as 'user or service account' unless explicitly stated otherwise." Read under that rule, this note tells an admin that service-account roles also can't be changed in Kosli once SCIM is on — and service accounts are never SCIM-provisioned, so the dropdown procedure below still applies to them in full.

For an admin who has just enabled SCIM and needs to change a CI service account's role, that's the difference between doing it in one minute and opening a support ticket. Say "people" explicitly, since the note is user-only:

Suggested change

	This procedure does not apply to users provisioned through [automated user provisioning](/administration/managing_users/automated_user_provisioning) — their roles cannot be changed in Kosli. Manage those roles through your identity provider groups instead.
	<Note>
	This procedure does not apply to people provisioned through [automated user provisioning](/administration/managing_users/automated_user_provisioning) — their roles cannot be changed in Kosli, so manage them through your identity provider groups instead. Service accounts are never provisioned this way, so their roles are always changed here.
	</Note>

Fix this →

[claude]

Suggestion — this section restates two things the reader has already been given, and names the auth provider two different ways.

• Line 84 "tell us which of your Kosli organizations you wish to have SCIM enabled for" is the same instruction as the prerequisite at lines 20-22 — and that prerequisite links here for the detail, so the reader follows a pointer and lands on the same sentence they came from.
• Line 86 "create a group for each of these roles… add your users to the groups" is the same instruction as Setup step 3 (lines 53-57), which also links here.
• Line 30 says "Kosli's auth provider"; line 84 says "our auth provider" for the same thing. The rest of these pages use "Kosli" rather than first person (single_sign_on.md:45 "your Kosli Customer Success representative").

Keeping only the naming scheme and the precedence rule here — the two facts that appear nowhere else — removes the round trip:

Suggested change

	## Roles for new and existing users
	Kosli supports role assignment through your IdP, so that users' [roles within Kosli](/administration/managing_users/roles_in_kosli) can be managed by your onboarding and IT teams, without requiring admin access to Kosli.
	You will need to tell us which of your Kosli organizations you wish to have SCIM enabled for; we will then create the necessary roles within our auth provider. Each organization will have four roles, with the names `kosli-<org-name>-<role>`, to correspond to the available roles in Kosli (admin, member, snapshotter, reader).
	Within your IdP you will need to create a group for each of these roles. You will then add your users to the groups corresponding to the organizations/roles you wish them to have in Kosli. If a member receives two different roles for the same organization, the highest-privilege role will be assigned.
	## Roles for new and existing users
	Kosli supports role assignment through your IdP, so that users' [roles within Kosli](/administration/managing_users/roles_in_kosli) can be managed by your onboarding and IT teams, without requiring admin access to Kosli.
	Kosli creates four roles per organization in its auth provider, named `kosli-<org-name>-<role>` — one for each Kosli role (admin, member, snapshotter, reader). Create a group in your IdP for each one you need.
	If a user ends up with two different roles for the same organization, the highest-privilege role wins.

[claude]

Suggestion — the SSO/SCIM procedure is split across two groups, and the human sign-in pages are last in a group that now opens with machine credentials.

All three pages are correctly listed (core rule 2 satisfied), but the grouping splits one job across two sidebar groups. automated_user_provisioning.md requires an SSO connection as a prerequisite (line 18), and its group-mapping steps are performed in the SSO Configuration wizard (line 91) — so an admin doing SCIM works in Users & roles and Authentication & access alternately. Its Diátaxis form is also a how-to about IdP configuration, like single_sign_on.md, not role reference like its two current siblings.

Leading with human sign-in also matters now that there are five entries: an admin arriving at "Authentication & access" meets three API-credential pages before the two pages about how people log in.

Suggested change

	"administration/authentication/api_authentication_methods",
	"administration/authentication/service_accounts",
	"administration/authentication/api_key_rotation"
	"administration/authentication/api_key_rotation",
	"administration/authentication/single_sign_on",
	"administration/authentication/magic_link"
	]
	},
	{
	"group": "Users & roles",
	"pages": [
	"administration/managing_users/roles_in_kosli",
	"administration/managing_users/mapping_users_to_roles"
	"administration/managing_users/mapping_users_to_roles",
	"administration/managing_users/automated_user_provisioning"
	]
	},
	"pages": [
	"administration/authentication/single_sign_on",
	"administration/authentication/magic_link",
	"administration/managing_users/automated_user_provisioning",
	"administration/authentication/api_authentication_methods",
	"administration/authentication/service_accounts",
	"administration/authentication/api_key_rotation"
	]
	},
	{
	"group": "Users & roles",
	"pages": [
	"administration/managing_users/roles_in_kosli",
	"administration/managing_users/mapping_users_to_roles"
	]
	},

Non-blocking, and the file path can stay under managing_users/ either way — but if you'd rather not move it, at least the two sign-in pages are worth promoting above the API pages.

[gsavage]

Closing to open again with a cleaner set of comments