diff --git a/administration/authentication/api_authentication_methods.md b/administration/authentication/api_authentication_methods.md new file mode 100644 index 0000000..ac5f49a --- /dev/null +++ b/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. | + + +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. + + +## 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 <>" \ + https://app.kosli.com/api/v2/environments/<> +``` + +## HTTP basic auth + + +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. + + +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 "<>:" \ + https://app.kosli.com/api/v2/environments/<> +``` + + +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. + + +Equivalently, set the `Authorization` header directly with the base64-encoded `<>:` string: + +```shell +curl -H "Authorization: Basic $(printf '%s:' "<>" | base64)" \ + https://app.kosli.com/api/v2/environments/<> +``` diff --git a/administration/authentication/api_key_rotation.md b/administration/authentication/api_key_rotation.md new file mode 100644 index 0000000..5e46d20 --- /dev/null +++ b/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) diff --git a/administration/authentication/service_accounts.md b/administration/authentication/service_accounts.md new file mode 100644 index 0000000..388f2dd --- /dev/null +++ b/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. + + +Service accounts are only available in shared organizations. + + +## Create a service account + + + + Sign in to Kosli and select the organization where the service account should live. + Navigate to **Settings → Service accounts**. + + + Click **Add new service account**, give it a descriptive name (e.g. `ci-github-actions`), and click **Add**. + + + 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**. + + + 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. + + + +## 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) diff --git a/administration/managing_users/mapping_users_to_roles.md b/administration/managing_users/mapping_users_to_roles.md new file mode 100644 index 0000000..c357db6 --- /dev/null +++ b/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) diff --git a/administration/managing_users/roles_in_kosli.md b/administration/managing_users/roles_in_kosli.md index 8274e64..c2b2ecd 100644 --- a/administration/managing_users/roles_in_kosli.md +++ b/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. + + +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. + ## Overview @@ -178,7 +182,7 @@ The following sections provide more details about each Kosli user role, includin -## 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. diff --git a/config/navigation.json b/config/navigation.json index 9937fab..32dba1a 100644 --- a/config/navigation.json +++ b/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" ] }, { diff --git a/config/redirects.json b/config/redirects.json index dc83816..84e3956 100644 --- a/config/redirects.json +++ b/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" } ] diff --git a/getting_started/authenticating_to_kosli.md b/getting_started/authenticating_to_kosli.md new file mode 100644 index 0000000..417e022 --- /dev/null +++ b/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) | + + +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. + + +## Quick start: get a token + + + + 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) + + + - **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. + + + 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. + + + +## Use the token + +Pass the token as a bearer token when calling the API directly: + +```shell +curl -H "Authorization: Bearer <>" \ + https://app.kosli.com/api/v2/environments/<> +``` + +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. diff --git a/getting_started/service-accounts.md b/getting_started/service-accounts.md deleted file mode 100644 index 0312120..0000000 --- a/getting_started/service-accounts.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Service Accounts" -description: "Learn how to create and manage Kosli Service Accounts and API keys." -icon: "user-gear" ---- - -Prior to engaging with Kosli, authentication is necessary. There are two methods to achieve this: - -1. Using a service account API key (recommended). -2. Using a personal API key. - -## Service Accounts - - -Service accounts are exclusively available within shared organizations. - - -A service account represents a machine user designed for interactions with Kosli from external systems, such as CI or runtime environments. - -To create a service account: - -- Log in to Kosli. -- From the left navigation menu, choose the organization where you wish to create the service account. -- Navigate to `Settings` in the left navigation menu. -- Select `Service accounts` from the settings sub-menu. -- Click `Add new service account`, provide a name for the service account, and click Add. -- Once created, generate an API key for the service account by clicking `Add API Key`. -- Choose a Time-To-Live (TTL) for the key, add a descriptive label, and then click `Add`. -- Ensure to copy the generated key as it won't be retrievable later. This key serves as the authentication token. - - -Kosli never stores your API token in plain text. Only a cryptographic hash of the token is stored, so the original token cannot be retrieved from our systems. - - -## Personal API Keys - - -Personal API keys possess equivalent permissions to your user account, encompassing access to multiple organizations. Therefore, exercise caution while using personal API keys. These keys grant access and perform actions as per the associated user's permissions across various organizations. - - -To create a personal API key: -- Login to Kosli -- From your user menu in the top right corner, click `Profile` -- In the API Keys section, click `Add API Key`, select a Time-To-Live (TTL) for the key, add a descriptive label, and then click `Add` -- Ensure to copy the generated key as it won't be retrievable later. This key serves as the authentication token. - - -## API Keys rotation - -You can execute a zero-downtime API key rotation by following these steps: - -- **Generate a New Key**: -Create a new API key that will replace the existing key. - -- **Replace the Old Key Where Used**: -Implement the new key in all areas where the old key is currently used for authentication or access. - -- **Delete the Old Key:** -Once the new key is in place and operational, remove or delete the old key from the system or applications where it was previously employed for security or authentication purposes. - -By systematically following these steps, you can ensure a seamless API key rotation without causing any downtime or interruptions in service. - -For a detailed walkthrough including API examples, see [Rotating API keys](/tutorials/rotating_api_keys). - - -## Using API Keys - -### In CLI - -you can assign an API key to any CLI command by one of the following options: -- using the `--api-token` flag -- exporting an environment variable called `KOSLI_API_TOKEN` -- setting it in a config file and passing the config file using `--config-file` (see [here](/getting_started/install#assigning-flags-via-config-files)) - -### In API - -When making requests against the Kosli API directly (e.g. using curl), you can authenticate your requests by setting the bearer token in the request Authorization header to your API key. - -```shell -curl -H "Authorization: Bearer <>" http://app.kosli.com/api/v2/environments/<> -``` \ No newline at end of file diff --git a/labs/lab-01-get-ready.mdx b/labs/lab-01-get-ready.mdx index 141d07b..4571797 100644 --- a/labs/lab-01-get-ready.mdx +++ b/labs/lab-01-get-ready.mdx @@ -109,7 +109,7 @@ This lab uses a simple Java application with a complete CI/CD pipeline already c Never commit API keys to your repository. You'll add this key to GitHub Secrets in Lab 2. - See [Service Accounts](/getting_started/service-accounts) for more on API key management. + See [Authenticating to Kosli](/getting_started/authenticating_to_kosli) for more on API key management. diff --git a/tutorials/attest_large_documents.md b/tutorials/attest_large_documents.md index 77c3372..e445fa2 100644 --- a/tutorials/attest_large_documents.md +++ b/tutorials/attest_large_documents.md @@ -11,7 +11,7 @@ This two-part approach keeps attestation payloads focused on what compliance rul ## Prerequisites * [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). * A Kosli flow and trail to attest to — follow the [Getting started guide](/getting_started/flows) if you need one. * A report file to attest (e.g. an SBOM in JSON format, or a SARIF vulnerability report). diff --git a/tutorials/attest_snyk.md b/tutorials/attest_snyk.md index ca7a8ef..abd5f54 100644 --- a/tutorials/attest_snyk.md +++ b/tutorials/attest_snyk.md @@ -13,7 +13,7 @@ To follow the steps in this tutorial, you need to: * [Install Helm](https://helm.sh/docs/intro/install/) if you want to try Snyk IaC attestations, otherwise skip. * [Install Docker](https://docs.docker.com/engine/install/) if you want to try Snyk container attestations, otherwise skip. * [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Setup diff --git a/tutorials/cli_and_http_proxy.md b/tutorials/cli_and_http_proxy.md index c581e35..90cc13c 100644 --- a/tutorials/cli_and_http_proxy.md +++ b/tutorials/cli_and_http_proxy.md @@ -14,7 +14,7 @@ If you already have an HTTP proxy running, skip to [Use the HTTP proxy with Kosl * [Install Docker](https://docs.docker.com/engine/install/). * [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Start the HTTP proxy diff --git a/tutorials/custom-attestation-ctrf.md b/tutorials/custom-attestation-ctrf.md index 07c0e00..cf6f9b5 100644 --- a/tutorials/custom-attestation-ctrf.md +++ b/tutorials/custom-attestation-ctrf.md @@ -9,7 +9,7 @@ By the end, you will have a reusable `ctrf` attestation type in Kosli that valid ## Prerequisites * [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). * A Kosli flow and trail to attest to — follow the [Getting started guide](/getting_started/flows) if you need one. ## Download the CTRF schema diff --git a/tutorials/evaluate_trails_with_opa.mdx b/tutorials/evaluate_trails_with_opa.mdx index a3796b1..7c8dbaf 100644 --- a/tutorials/evaluate_trails_with_opa.mdx +++ b/tutorials/evaluate_trails_with_opa.mdx @@ -14,7 +14,7 @@ In this tutorial, you'll write and evaluate policies against real trails in publ To follow this tutorial, you need to: * [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). * Set the `KOSLI_API_TOKEN` environment variable to your token: ```shell diff --git a/tutorials/following_a_git_commit_to_runtime_environments.md b/tutorials/following_a_git_commit_to_runtime_environments.md index a23c028..6e604d7 100644 --- a/tutorials/following_a_git_commit_to_runtime_environments.md +++ b/tutorials/following_a_git_commit_to_runtime_environments.md @@ -16,7 +16,7 @@ The commit we follow fixed a misconfiguration: `runner` should run with three re ## Prerequisites * [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Setup diff --git a/tutorials/querying_kosli.md b/tutorials/querying_kosli.md index 92384c8..7ac46c2 100644 --- a/tutorials/querying_kosli.md +++ b/tutorials/querying_kosli.md @@ -11,7 +11,7 @@ We will query **cyber-dojo**, an open-source project whose Kosli data is public. ## Prerequisites * [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Setup diff --git a/tutorials/report_aws_envs.md b/tutorials/report_aws_envs.md index 98e5539..c65ce62 100644 --- a/tutorials/report_aws_envs.md +++ b/tutorials/report_aws_envs.md @@ -16,7 +16,7 @@ Follow the section that matches your needs. * Have access to AWS. * [Create an ECS, Lambda, or S3 Kosli environment](/getting_started/environments#create-an-environment) named `aws-env-tutorial`. -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Report using Kosli CLI diff --git a/tutorials/report_cloud_run_envs.md b/tutorials/report_cloud_run_envs.md index 1359767..4071ec7 100644 --- a/tutorials/report_cloud_run_envs.md +++ b/tutorials/report_cloud_run_envs.md @@ -18,7 +18,7 @@ Follow the section that matches your needs. * Have access to a Google Cloud project and region with Cloud Run resources. * [Create a Cloud Run Kosli environment](/getting_started/environments#create-an-environment) named `cloud-run-tutorial`. -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Report using Kosli CLI diff --git a/tutorials/report_k8s_envs.md b/tutorials/report_k8s_envs.md index ed238e8..249a436 100644 --- a/tutorials/report_k8s_envs.md +++ b/tutorials/report_k8s_envs.md @@ -9,7 +9,7 @@ By the end of this tutorial, you will have reported a snapshot of your Kubernete * Have access to a Kubernetes cluster. * [Create a Kubernetes Kosli environment](/getting_started/environments#create-an-environment) named `k8s-tutorial`. -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Report a snapshot diff --git a/tutorials/repositories.md b/tutorials/repositories.md index 01ccded..f3e6bf3 100644 --- a/tutorials/repositories.md +++ b/tutorials/repositories.md @@ -15,7 +15,7 @@ This is useful when you need to: ## Prerequisites - [Install Kosli CLI](/getting_started/install) (v2.11.35 or higher). -- [Get a Kosli API token](/getting_started/service-accounts). +- [Get a Kosli API token](/getting_started/authenticating_to_kosli). - Have a [Flow](/getting_started/flows) and [Trail](/getting_started/trails) already created. ## Setup diff --git a/tutorials/rotating_api_keys.mdx b/tutorials/rotating_api_keys.mdx index 9e673c1..f1d1a4e 100644 --- a/tutorials/rotating_api_keys.mdx +++ b/tutorials/rotating_api_keys.mdx @@ -11,7 +11,7 @@ Kosli never stores your API token in plain text. Only a cryptographic hash of th ## Prerequisites -- A Kosli shared organization with at least one [service account](/getting_started/service-accounts#service-accounts) and an existing API key. +- A Kosli shared organization with at least one [service account](/administration/authentication/service_accounts) and an existing API key. - Administrator access to the organization that owns the service account. - An inventory of every system (CI pipelines, runtime reporters, scripts, secrets managers, etc.) that uses the API key you plan to rotate. @@ -106,7 +106,7 @@ Automating rotation from your secrets manager — using the rotate endpoint abov ## Related -- [Service Accounts](/getting_started/service-accounts) +- [Service accounts](/administration/authentication/service_accounts) - [Rotate an API key for a service account (API reference)](/api-reference/service-accounts/rotate-an-api-key-for-a-service-account) - [Revoke an API key for a service account (API reference)](/api-reference/service-accounts/revoke-an-api-key-for-a-service-account) - [List API keys for a service account (API reference)](/api-reference/service-accounts/list-api-keys-for-a-service-account) diff --git a/tutorials/tracing_a_production_incident_back_to_git_commits.md b/tutorials/tracing_a_production_incident_back_to_git_commits.md index e7cbeb6..672967d 100644 --- a/tutorials/tracing_a_production_incident_back_to_git_commits.md +++ b/tutorials/tracing_a_production_incident_back_to_git_commits.md @@ -12,7 +12,7 @@ By the end of this tutorial, you will have traced a production incident from a 5 ## Prerequisites * [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Setup diff --git a/tutorials/try_kosli_locally.mdx b/tutorials/try_kosli_locally.mdx index 680f873..d762ad6 100644 --- a/tutorials/try_kosli_locally.mdx +++ b/tutorials/try_kosli_locally.mdx @@ -19,7 +19,7 @@ artifacts are running in your runtime environment. - Install Docker. - [Install Kosli CLI](/getting_started/install). -- [Get a Kosli API token](/getting_started/service-accounts). +- [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Steps diff --git a/tutorials/unauthorized_iac_changes.md b/tutorials/unauthorized_iac_changes.md index 3d31777..fceed5b 100644 --- a/tutorials/unauthorized_iac_changes.md +++ b/tutorials/unauthorized_iac_changes.md @@ -14,7 +14,7 @@ This tutorial focuses on detecting changes made by bypassing the approved Terraf * [Install Terraform](https://developer.hashicorp.com/terraform/install). * [Install Snyk CLI](https://docs.snyk.io/snyk-cli/getting-started-with-the-snyk-cli#install-the-snyk-cli-and-authenticate-your-machine) (optional — needed for the security scan step). * [Install Kosli CLI](/getting_started/install). -* [Get a Kosli API token](/getting_started/service-accounts). +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). ## Setup diff --git a/administration/managing_organizations.md b/user/default_organization.md similarity index 85% rename from administration/managing_organizations.md rename to user/default_organization.md index 6db883a..6eac6af 100644 --- a/administration/managing_organizations.md +++ b/user/default_organization.md @@ -1,6 +1,7 @@ --- -title: Managing Organizations -description: Manage your Kosli organization preferences, including which organization the app opens to when you sign in. +title: Default organization +description: Pick which Kosli organization the app opens to when you sign in. +icon: "building" --- If you belong to more than one Kosli organization, you can pick a default. The Kosli app will open to that organization each time you sign in. diff --git a/user/personal_api_keys.md b/user/personal_api_keys.md new file mode 100644 index 0000000..58df90b --- /dev/null +++ b/user/personal_api_keys.md @@ -0,0 +1,36 @@ +--- +title: Personal API keys +description: Create and manage personal API keys tied to your Kosli user account. +icon: "key" +--- + +A personal API key authenticates as **you**. It inherits your permissions across every organization you belong to. + + +For CI/CD pipelines and any other automation, use a [service account](/administration/authentication/service_accounts) instead. Service account keys are scoped to a single organization, have an explicit role, and produce cleaner audit trails. + + +## Create a personal API key + + + + From the user menu in the top-right corner of the Kosli app, click **Profile**: + + - EU: [app.kosli.com/settings/profile](https://app.kosli.com/settings/profile) + - US: [app.us.kosli.com/settings/profile](https://app.us.kosli.com/settings/profile) + + + In the **API keys** section, click **Add API key**. Choose a Time-To-Live (TTL), add a descriptive label, and click **Add**. + + + Kosli stores only a cryptographic hash of the token. The original value is shown once and cannot be retrieved later. + + + +## Use the key + +The same usage applies as for service account keys — see [Authenticating to Kosli](/getting_started/authenticating_to_kosli#use-the-token). + +## Revoke a key + +To revoke a personal API key, open **Profile → API keys**, find the key, and click **Revoke**. The key stops working immediately.