From 89d28a497bccc73608844114f09b8f5d32cad5ec Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 24 Jun 2026 14:50:50 +0000 Subject: [PATCH 1/4] docs: add CLI tab for rotating API keys tutorial --- tutorials/rotating_api_keys.mdx | 100 ++++++++++++++++++++++---------- 1 file changed, 69 insertions(+), 31 deletions(-) diff --git a/tutorials/rotating_api_keys.mdx b/tutorials/rotating_api_keys.mdx index f1d1a4e..bff4000 100644 --- a/tutorials/rotating_api_keys.mdx +++ b/tutorials/rotating_api_keys.mdx @@ -25,37 +25,75 @@ When you rotate a service account API key, Kosli: The grace period lets you roll the new key out to all consumers without an interruption in service. Choose a window that matches your deployment cadence — short enough to limit exposure, long enough to update every dependent system. -## Rotate a key from the Kosli web app - -1. Log in to Kosli and select the organization that owns the service account. -2. Go to **Settings** → **Service accounts** in the left navigation. -3. Open the service account whose key you want to rotate. -4. Find the key in the **API Keys** list and click **Regenerate**. -5. Choose a grace period for the old key, then confirm. -6. Copy the new key value immediately and store it in your secrets manager — it will not be shown again. - -## Rotate a key via the API - -You can also rotate keys programmatically, which is useful for automating periodic rotation from your CI or a secrets manager. - -```shell -curl -X POST \ - -H "Authorization: Bearer <>" \ - -H "Content-Type: application/json" \ - -d '{"grace_period_hours": 24}' \ - https://app.kosli.com/api/v2/service-accounts/<>/<>/api-keys/<>/rotate -``` - -The response contains the new API key value. Capture it directly into your secrets store: - -```shell -NEW_KEY=$(curl -s -X POST \ - -H "Authorization: Bearer $KOSLI_ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"grace_period_hours": 24}' \ - https://app.kosli.com/api/v2/service-accounts/$ORG/$SA_NAME/api-keys/$KEY_ID/rotate \ - | jq -r '.api_key') -``` +## Rotate a key + +Choose the interface that best fits your workflow. All three trigger the same rotation flow described above. + + + + 1. Log in to Kosli and select the organization that owns the service account. + 2. Go to **Settings** → **Service accounts** in the left navigation. + 3. Open the service account whose key you want to rotate. + 4. Find the key in the **API Keys** list and click **Regenerate**. + 5. Choose a grace period for the old key, then confirm. + 6. Copy the new key value immediately and store it in your secrets manager — it will not be shown again. + + + + Use the [`kosli rotate api-key`](/client_reference/kosli_rotate_api-key) command to rotate one or more keys from your terminal or a CI job: + + ```shell + kosli rotate api-key <> \ + --service-account <> \ + --grace-period-hours 24 \ + --api-token "$KOSLI_ADMIN_TOKEN" \ + --org "$ORG" + ``` + + Rotate multiple keys for the same service account in one call by passing additional key IDs: + + ```shell + kosli rotate api-key keyID1 keyID2 \ + --service-account <> \ + --api-token "$KOSLI_ADMIN_TOKEN" \ + --org "$ORG" + ``` + + Use `--output json` to capture the new key value programmatically: + + ```shell + NEW_KEY=$(kosli rotate api-key <> \ + --service-account <> \ + --api-token "$KOSLI_ADMIN_TOKEN" \ + --org "$ORG" \ + --output json \ + | jq -r '.api_key') + ``` + + + + Call the rotate endpoint directly — useful when integrating with a secrets manager or another automation system: + + ```shell + curl -X POST \ + -H "Authorization: Bearer <>" \ + -H "Content-Type: application/json" \ + -d '{"grace_period_hours": 24}' \ + https://app.kosli.com/api/v2/service-accounts/<>/<>/api-keys/<>/rotate + ``` + + The response contains the new API key value. Capture it directly into your secrets store: + + ```shell + NEW_KEY=$(curl -s -X POST \ + -H "Authorization: Bearer $KOSLI_ADMIN_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"grace_period_hours": 24}' \ + https://app.kosli.com/api/v2/service-accounts/$ORG/$SA_NAME/api-keys/$KEY_ID/rotate \ + | jq -r '.api_key') + ``` + + You can list a service account's keys (including the rotation status of the old key) with `GET /service-accounts/{org}/{name}/api-keys`. See the [API reference](/api-reference/service-accounts/list-api-keys-for-a-service-account) for details. From d5a4cff38a8977d423d2038018c76117791edb39 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 24 Jun 2026 15:08:48 +0000 Subject: [PATCH 2/4] docs: mention CLI in rotating API keys intro --- tutorials/rotating_api_keys.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/rotating_api_keys.mdx b/tutorials/rotating_api_keys.mdx index bff4000..b90d05f 100644 --- a/tutorials/rotating_api_keys.mdx +++ b/tutorials/rotating_api_keys.mdx @@ -3,7 +3,7 @@ title: Rotating API keys description: Learn how to rotate Kosli service account API keys with zero downtime. --- -Rotating API keys regularly is a security best practice that limits the blast radius of a leaked or compromised credential. This tutorial walks you through rotating a Kosli service account API key with zero downtime, using either the Kosli web app or the API directly. +Rotating API keys regularly is a security best practice that limits the blast radius of a leaked or compromised credential. This tutorial walks you through rotating a Kosli service account API key with zero downtime, using the Kosli web app, the CLI, or the API directly. 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 — make sure to copy a new key immediately after creating or rotating it. From 336bb49e1a84156220b42664ba24ec9e87e69507 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 24 Jun 2026 15:13:43 +0000 Subject: [PATCH 3/4] docs: clarify grace period in multi-key rotate example --- tutorials/rotating_api_keys.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tutorials/rotating_api_keys.mdx b/tutorials/rotating_api_keys.mdx index b90d05f..b5b7e6d 100644 --- a/tutorials/rotating_api_keys.mdx +++ b/tutorials/rotating_api_keys.mdx @@ -50,11 +50,12 @@ Choose the interface that best fits your workflow. All three trigger the same ro --org "$ORG" ``` - Rotate multiple keys for the same service account in one call by passing additional key IDs: + Rotate multiple keys for the same service account in one call by passing additional key IDs. When `--grace-period-hours` is omitted, the server-side default grace period applies: ```shell kosli rotate api-key keyID1 keyID2 \ --service-account <> \ + --grace-period-hours 24 \ --api-token "$KOSLI_ADMIN_TOKEN" \ --org "$ORG" ``` From ff444e57fe94f2e351e35897394ed285dc672252 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 24 Jun 2026 15:17:10 +0000 Subject: [PATCH 4/4] docs: drop grace-period flag from multi-key rotate example --- tutorials/rotating_api_keys.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/tutorials/rotating_api_keys.mdx b/tutorials/rotating_api_keys.mdx index b5b7e6d..5166058 100644 --- a/tutorials/rotating_api_keys.mdx +++ b/tutorials/rotating_api_keys.mdx @@ -55,7 +55,6 @@ Choose the interface that best fits your workflow. All three trigger the same ro ```shell kosli rotate api-key keyID1 keyID2 \ --service-account <> \ - --grace-period-hours 24 \ --api-token "$KOSLI_ADMIN_TOKEN" \ --org "$ORG" ```