docs: restructure authentication docs

administration/authentication/api_authentication_methods.md

@@ -0,0 +1,61 @@
+---
+title: API authentication methods
+description: How to authenticate to the Kosli API using bearer tokens or HTTP basic auth.
+icon: "shield-halved"
+---
+
+The Kosli API supports two authentication methods:
+
+| Method | Status | When to use |
+|--------|--------|-------------|
+| [Bearer token](#bearer-token) | **Recommended** | All new integrations. Works for service account and personal API keys. |
+| [HTTP basic auth](#http-basic-auth) | Legacy | Fallback for tools that cannot send an `Authorization: Bearer` header. |
+
+<Tip>
+If you are integrating Kosli for the first time, use bearer tokens. Basic auth remains supported for backwards compatibility but is not the recommended path.
+</Tip>
+
+## Bearer token
+
+Bearer tokens work with both [service account](/administration/authentication/service_accounts) and [personal](/user/personal_api_keys) API keys.
+
+### In the CLI
+
+Pass the token to any `kosli` command using one of:
+
+- The `--api-token` flag.
+- The `KOSLI_API_TOKEN` environment variable.
+- A config file passed via `--config-file` — see [Assigning flags via config files](/getting_started/install#assigning-flags-via-config-files).
+
+### In API requests
+
+Send the token in the `Authorization` header:
+
+```shell
+curl -H "Authorization: Bearer <<your-api-key>>" \
+  https://app.kosli.com/api/v2/environments/<<your-org-name>>
+```
+
+## HTTP basic auth
+
+<Note>
+HTTP basic auth is a legacy method kept for backwards compatibility with tools that cannot send an `Authorization: Bearer` header. For all new integrations, use bearer tokens instead.
+</Note>
+
+Kosli accepts HTTP basic auth as an alternative to bearer tokens. The API key is sent as the **username**; the password is ignored.
+
+```shell
+curl -u "<<your-api-key>>:" \
+  https://app.kosli.com/api/v2/environments/<<your-org-name>>
+```
+
+<Warning>
+The trailing colon (`:`) is required. Without it, `curl` treats the whole string as a username with no password and **prompts interactively** for one — at which point the API key may already be visible in the prompt or shell history (especially when the key comes from an environment variable). The value after the colon can be anything, including empty; Kosli ignores it.
+</Warning>
+
+Equivalently, set the `Authorization` header directly with the base64-encoded `<<your-api-key>>:` string:
+
+```shell
+curl -H "Authorization: Basic $(printf '%s:' "<<your-api-key>>" | base64)" \
+  https://app.kosli.com/api/v2/environments/<<your-org-name>>
+```

administration/authentication/api_key_rotation.md

@@ -0,0 +1,25 @@
+---
+title: API key rotation
+description: Reference for how Kosli API key rotation works, including grace periods and the rotation API.
+icon: "arrows-rotate"
+---
+
+Rotating API keys regularly limits the blast radius of a leaked credential. Kosli supports **zero-downtime rotation** for service account API keys: a new key is issued immediately while the old key remains valid for a configurable grace period.
+
+## How rotation works
+
+When you rotate a service account API key, Kosli:
+
+1. Generates a new API key and returns its value once.
+2. Keeps the old key valid for a configurable grace period (default: **24 hours**).
+3. Automatically revokes the old key when the grace period expires.
+
+Choose a grace period that fits your deployment cadence — long enough to roll the new key out to every consumer, short enough to limit exposure.
+
+## Where next
+
+- [Rotating API keys (tutorial)](/tutorials/rotating_api_keys) — step-by-step walkthrough in the web app and via the API.
+- [Service accounts](/administration/authentication/service_accounts) — service account lifecycle.
+- [Rotate an API key (API reference)](/api-reference/service-accounts/rotate-an-api-key-for-a-service-account)
+- [Revoke an API key (API reference)](/api-reference/service-accounts/revoke-an-api-key-for-a-service-account)
+- [List API keys (API reference)](/api-reference/service-accounts/list-api-keys-for-a-service-account)

administration/authentication/service_accounts.md

@@ -0,0 +1,47 @@
+---
+title: Service accounts
+description: Create and manage service accounts and their API keys for machine-to-machine access to Kosli.
+icon: "user-gear"
+---
+
+A **service account** is a machine user. Use service accounts for any non-human caller — CI pipelines, runtime reporters, scripts, and other automation — so that credentials and audit trails are tied to a system rather than a person.
+
+<Warning>
+Service accounts are only available in shared organizations.
+</Warning>
+
+## Create a service account
+
+<Steps>
+  <Step title="Open the organization's settings">
+    Sign in to Kosli and select the organization where the service account should live.
+    Navigate to **Settings → Service accounts**.
+  </Step>
+  <Step title="Add the service account">
+    Click **Add new service account**, give it a descriptive name (e.g. `ci-github-actions`), and click **Add**.
+  </Step>
+  <Step title="Generate an API key">
+    On the new service account, click **Add API key**. Choose a Time-To-Live (TTL), add a label that identifies where the key will be used, and click **Add**.
+  </Step>
+  <Step title="Copy the key immediately">
+    Kosli stores only a cryptographic hash of the token. The original value is shown once and cannot be retrieved later — paste it directly into your secret store.
+  </Step>
+</Steps>
+
+## Assign a role
+
+Service accounts have the same role model as users: **Admin**, **Member**, **Snapshotter**, or **Reader**. The role determines what the service account can do in the organization. Pick the least-privileged role that fits the workload.
+
+See [Roles in Kosli](/administration/managing_users/roles_in_kosli) for the full permissions matrix. As a starting point:
+
+- **Member** — CI/CD systems that report attestations, manage flows, and create resources.
+- **Snapshotter** — runtime reporters that only record environment snapshots.
+- **Reader** — read-only systems such as dashboards or query tooling.
+- **Admin** — rarely needed; reserve for automation that manages users, roles, or organization-wide settings (for example, Terraform-driven org bootstrap).
+
+## Rotate or revoke keys
+
+For zero-downtime rotation and the API-driven flow, see:
+
+- [API key rotation (reference)](/administration/authentication/api_key_rotation)
+- [Rotating API keys (tutorial)](/tutorials/rotating_api_keys)

administration/managing_users/mapping_users_to_roles.md

@@ -0,0 +1,33 @@
+---
+title: Mapping users to roles
+description: Recommended mappings from common organizational roles to Kosli roles.
+---
+
+When implementing Kosli, you need to map organizational roles to [Kosli roles](/administration/managing_users/roles_in_kosli). This table provides recommended mappings based on typical responsibilities:
+
+| Organizational Role | Recommended Kosli Role | Alternative | Rationale |
+|---------------------|------------------------|-------------|-----------|
+| **Platform Engineers** | Member | Admin (for leads) | Platform engineers need to set up flows, manage service accounts, configure integrations, and implement Kosli across teams. Member role provides these capabilities. Lead platform engineers managing the overall setup may need Admin access. |
+| **Application Developers** | Member | Reader (for view-only) | Developers typically need to report attestations and manage flows for their applications. Member role enables this. Some developers may only need visibility into deployments and compliance status, making Reader sufficient. |
+| **Security & Compliance** | Admin | N/A | Security and compliance teams need to manage policies, review audit data, control user access, and configure organization-wide settings. Admin role is required for these governance responsibilities. |
+| **Sponsors** | Reader | N/A | Sponsors need visibility into adoption progress, compliance status, and overall system health but don't need to make technical changes. Reader role provides necessary oversight without operational access. |
+
+## Understanding the mapping
+
+This mapping is a starting point. Your organization's structure and responsibilities may require adjustments:
+
+- **Small teams**: Developers might need Admin access if they handle all aspects
+- **Large enterprises**: Strict separation may require more Readers, fewer Admins
+- **Regulated industries**: Security teams might need dedicated Admin accounts separate from operations
+
+The key principle: Assign the minimum role required for someone to fulfill their responsibilities effectively.
+
+## Learn more about organizational roles
+
+For detailed guidance on each organizational role's responsibilities during Kosli implementation, see:
+
+- [Implementation Guide: Roles and Responsibilities](/implementation_guide/phase_1/roles_and_responsibilities/overview)
+- [Platform Engineers](/implementation_guide/phase_1/roles_and_responsibilities/platform_engineers)
+- [Application Developers](/implementation_guide/phase_1/roles_and_responsibilities/app_developers)
+- [Security & Compliance](/implementation_guide/phase_1/roles_and_responsibilities/security_compliance)
+- [Sponsors](/implementation_guide/phase_1/roles_and_responsibilities/sponsors)

administration/managing_users/roles_in_kosli.md

@@ -1,8 +1,12 @@
 ---
 title: Roles in Kosli
-description: Understand the different user roles in Kosli and their permissions to manage access within your organization.
+description: Understand the roles in Kosli and their permissions to manage access for users and service accounts within your organization.
 ---
-Kosli provides three user roles to help administrators manage access and permissions within their organization. Understanding these roles is essential for assigning the appropriate level of access to your team members.
+Kosli uses a single role model that applies to both **users** and **[service accounts](/administration/authentication/service_accounts)**. Understanding these roles is essential for assigning the appropriate level of access to your team members and to the automated systems that talk to Kosli on their behalf.
+
+<Note>
+Roles apply to service accounts the same way they apply to users. Wherever this page mentions a "user", read it as "user or service account" unless explicitly stated otherwise. The only role-related capability that is user-only is being invited to or removed from the organization.
+</Note>
 
 ## Overview
 
@@ -178,7 +182,7 @@ The following sections provide more details about each Kosli user role, includin
   </Accordion>
 
 
-## Assigning Roles
+## Assigning roles
 
 To assign or change a user's role:
 
@@ -194,21 +198,21 @@ Role changes take effect immediately. Users will see their updated permissions t
 
 ---
 
-## Best Practices
+## Best practices
 
-### Follow the Principle of Least Privilege
+### Follow the principle of least privilege
 
 Assign users the minimum role required to perform their job functions. Start with Reader access and increase permissions as needed.
 
-### Use Service Accounts for Automation
+### Use service accounts for automation
 
 For CI/CD pipelines and automated systems, create service accounts with the Member role rather than using personal API keys. This provides better auditability and security.
 
-### Regular Access Reviews
+### Regular access reviews
 
 Periodically review user roles and remove access for team members who no longer need it. This is especially important when people change roles or leave the organization.
 
-### Separate Concerns
+### Separate concerns
 
 - **Admins**: Focus on governance, security, and organization-wide configuration
 - **Members**: Handle day-to-day operations and resource management
@@ -217,33 +221,7 @@ Periodically review user roles and remove access for team members who no longer
 
 ---
 
-## Mapping Roles to Your Organization
-
-When implementing Kosli, you need to map organizational roles to Kosli user roles. This table provides recommended mappings based on typical responsibilities:
-
-| Organizational Role | Recommended Kosli Role | Alternative | Rationale |
-|---------------------|------------------------|-------------|-----------|
-| **Platform Engineers** | Member | Admin (for leads) | Platform engineers need to set up flows, manage service accounts, configure integrations, and implement Kosli across teams. Member role provides these capabilities. Lead platform engineers managing the overall setup may need Admin access. |
-| **Application Developers** | Member | Reader (for view-only) | Developers typically need to report attestations and manage flows for their applications. Member role enables this. Some developers may only need visibility into deployments and compliance status, making Reader sufficient. |
-| **Security & Compliance** | Admin | N/A | Security and compliance teams need to manage policies, review audit data, control user access, and configure organization-wide settings. Admin role is required for these governance responsibilities. |
-| **Sponsors** | Reader | N/A | Sponsors need visibility into adoption progress, compliance status, and overall system health but don't need to make technical changes. Reader role provides necessary oversight without operational access. |
-
-### Understanding the Mapping
-
-This mapping is a starting point. Your organization's structure and responsibilities may require adjustments:
-
-- **Small teams**: Developers might need Admin access if they handle all aspects
-- **Large enterprises**: Strict separation may require more Readers, fewer Admins
-- **Regulated industries**: Security teams might need dedicated Admin accounts separate from operations
-
-The key principle: Assign the minimum role required for someone to fulfill their responsibilities effectively.
-
-### Learn More About Organizational Roles
-
-For detailed guidance on each organizational role's responsibilities during Kosli implementation, see:
+## See also
 
-- [Implementation Guide: Roles and Responsibilities](implementation_guide/phase_1/roles_and_responsibilities)
-- [Platform Engineers](implementation_guide/phase_1/roles_and_responsibilities/platform_engineers)
-- [Application Developers](implementation_guide/phase_1/roles_and_responsibilities/app_developers)
-- [Security & Compliance](implementation_guide/phase_1/roles_and_responsibilities/security_compliance)
-- [Sponsors](implementation_guide/phase_1/roles_and_responsibilities/sponsors)
+- [Mapping users to roles](/administration/managing_users/mapping_users_to_roles) — recommended Kosli roles for common organizational roles.
+- [Service accounts](/administration/authentication/service_accounts) — assigning roles to machine users.

config/navigation.json

@@ -20,7 +20,7 @@
           "icon": "rocket",
           "pages": [
             "getting_started/install",
-            "getting_started/service-accounts",
+            "getting_started/authenticating_to_kosli",
             "getting_started/flows",
             "getting_started/trails",
             "getting_started/artifacts",
@@ -31,15 +31,31 @@
             "getting_started/approvals"
           ]
         },
+        {
+          "group": "User",
+          "icon": "user",
+          "pages": [
+            "user/default_organization",
+            "user/personal_api_keys"
+          ]
+        },
         {
           "group": "Administration",
           "icon": "cog",
           "pages": [
-            "administration/managing_organizations",
             {
-              "group": "Managing Users",
+              "group": "Authentication & access",
+              "pages": [
+                "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/roles_in_kosli",
+                "administration/managing_users/mapping_users_to_roles"
               ]
             },
             {

config/redirects.json

@@ -54,5 +54,13 @@
   {
     "source": "/api_v2",
     "destination": "/api-reference/actions/list-actions"
+  },
+  {
+    "source": "/getting_started/service-accounts",
+    "destination": "/getting_started/authenticating_to_kosli"
+  },
+  {
+    "source": "/administration/managing_organizations",
+    "destination": "/user/default_organization"
   }
 ]

getting_started/authenticating_to_kosli.md

@@ -0,0 +1,53 @@
+---
+title: Authenticating to Kosli
+description: How to get an API token for the Kosli CLI and API, and where to manage credentials.
+icon: "key"
+---
+
+Most interactions with Kosli — from the CLI, the API, or CI/CD pipelines — require an API token. This page covers the quickest path to getting one and points to the deeper documentation for each topic.
+
+## Pick a credential type
+
+| Use case | Credential | Where to manage it |
+|----------|------------|--------------------|
+| CI/CD, runtime reporters, automation | **Service account API key** (recommended) | [Service accounts](/administration/authentication/service_accounts) |
+| Interactive scripts tied to your user | **Personal API key** | [Personal API keys](/user/personal_api_keys) |
+
+<Tip>
+For anything automated, use a service account. Personal API keys inherit your user's permissions across every organization you belong to, which is rarely what you want for a pipeline.
+</Tip>
+
+## Quick start: get a token
+
+<Steps>
+  <Step title="Sign in to Kosli">
+    Open the Kosli web app and sign in:
+
+    - EU: [app.kosli.com](https://app.kosli.com)
+    - US: [app.us.kosli.com](https://app.us.kosli.com)
+  </Step>
+  <Step title="Create a key">
+    - **For CI/CD**, follow [Service accounts](/administration/authentication/service_accounts) to create a service account and generate its first API key.
+    - **For your own scripts**, follow [Personal API keys](/user/personal_api_keys) to generate a key tied to your user.
+  </Step>
+  <Step title="Copy the key immediately">
+    Kosli stores only a hash of the token, so the original is shown once and cannot be retrieved later. Paste it straight into your secret store.
+  </Step>
+</Steps>
+
+## Use the token
+
+Pass the token as a bearer token when calling the API directly:
+
+```shell
+curl -H "Authorization: Bearer <<your-api-key>>" \
+  https://app.kosli.com/api/v2/environments/<<your-org-name>>
+```
+
+For CLI usage, basic auth, and full examples, see [API authentication methods](/administration/authentication/api_authentication_methods).
+
+## See also
+
+- [Service accounts](/administration/authentication/service_accounts) — admin lifecycle for machine credentials.
+- [API key rotation](/administration/authentication/api_key_rotation) — how rotation works, with a [step-by-step tutorial](/tutorials/rotating_api_keys).
+- [Roles in Kosli](/administration/managing_users/roles_in_kosli) — what users and service accounts can do at each role.