docs: restructure authentication docs

[dangrondahl]

Summary

Restructure scattered authentication content into a clear three-part spine:

• Getting started → Authenticating to Kosli — short intro pointing readers at the right deep page.
• Administration → Authentication & access (new group) — service accounts admin lifecycle, API authentication methods (bearer + basic auth), and API key rotation reference.
• User (new top-level group) — personal-account settings: default organization (moved from Administration, where it was misfiled) and personal API keys.

Other changes in this PR:

• Renames the Managing Users sidebar group to Users & roles.
• Splits the role-mapping content out of roles_in_kosli.md into a new mapping_users_to_roles.md page.
• Clarifies that Kosli roles apply equally to users and service accounts.
• Documents HTTP basic auth (closes Document Basic Auth for API authentication #89), including the trailing-colon gotcha that would otherwise prompt for a password and leak the key.
• Adds redirects for both moved URLs and updates all internal cross-links across tutorials and labs.

Test plan

• `mint broken-links` passes
• `mint dev` — manually click through:
  • Getting started → Authenticating to Kosli
  • Administration → Authentication & access (all 3 pages)
  • User → Default organization, Personal API keys
  • Old URLs (`/administration/managing_organizations`, `/getting_started/service-accounts`) redirect to the new locations
• Confirmed the documented HTTP basic auth curl example works against the live API

[mintlify]

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

Project	Status	Preview	Updated (UTC)
kosli	🟢 Ready	View Preview	Jun 5, 2026, 10:17 AM

[claude]

Claude finished @dangrondahl's task in 1m 58s —— View job

---

Review: PR #256 — Authentication docs restructure

• Read CLAUDE.md and doc-review skill
• Read all changed content files (27 files)
• Verify navigation.json includes all new pages
• Check for relative links and broken cross-references
• Check redirects coverage
• Post review findings

---

Overall assessment

This is a well-structured reorganization. The three-part spine (Getting started landing page → Administration auth group → User personal settings) is a clear improvement over the previous single service-accounts page. All new pages are registered in navigation.json, all old URLs have redirects, all internal cross-links have been updated consistently across 15 tutorial/lab files, and there are no relative links. The content quality is high — the HTTP basic auth trailing-colon warning is a particularly good addition.

The previous review round (6 comments) already covered the main suggestions. Most of those were non-blocking and several have been addressed in subsequent commits (least-privilege guidance, personal key revocation section). I have a few additional observations below.

---

Findings

Improvement

administration/managing_users/roles_in_kosli.md — old relative links fixed in the split
The original roles_in_kosli.md contained relative links in the "Mapping Roles" section (e.g., (implementation_guide/phase_1/roles_and_responsibilities) without a leading /). These have been correctly converted to root-relative paths in the new mapping_users_to_roles.md. Good catch — this was a pre-existing CLAUDE.md violation that this PR fixes as a side effect.

user/default_organization.md:25 — missing trailing period
The last sentence (You can also set your default organization via the [API](...).) is missing a period in the source. Minor, but every other page in this PR ends its final sentence with proper punctuation.

Suggestion

getting_started/authenticating_to_kosli.md — consider cross-linking to roles
The "Pick a credential type" table sends readers to the right pages for creating keys, but doesn't mention roles. A reader creating a service account for the first time would benefit from a brief note like "See Roles in Kosli for help choosing a role" in the table's "Where to manage it" column — the "See also" section at the bottom already links it, but readers following the quick-start flow may not scroll that far.

Navigation ordering — "User" group placement
The "User" group currently sits between "Getting started" and "Administration" in navigation.json. This is reasonable since it contains personal settings, but it could also be argued that it belongs after "Administration" since admin docs are a more natural continuation of the getting-started flow. Not blocking — just flagging for consideration as the nav evolves.

api_key_rotation.md — very short page
At 25 lines, this page is essentially a "How rotation works" paragraph plus links. That's fine as a reference entry point, but if more rotation details land later (personal key rotation, automated cadence recommendations), this page is the natural place to grow. No action needed now.

---

Summary

Category	Count
Critical	0
Improvement	2
Suggestion	3

Strong PR. The information architecture is much clearer, the HTTP basic auth documentation fills a real gap, and the migration mechanics (redirects, cross-link updates) are thorough. No blocking issues found.