Skip to content

Commit fe5ad72

Browse files
mintlify[bot]mintlify[bot]
authored
docs: add CLI option to rotating API keys tutorial (#289)
Restructures the "Rotate a key" section in the Rotating API keys tutorial into a `<Tabs>` block with three options: **Web UI**, **CLI**, and **API**. - Adds a new CLI tab covering `kosli rotate api-key`, including single-key, multi-key, and JSON-output (`jq`) capture variants, with a link to the command reference. - Preserves the existing Web UI steps and API/`curl` examples as separate tabs. - No content removed; only restructured for parity across interfaces. <!-- mintlify-agent-attribution --> --- Generated by Mintlify Agent. Requested by: marko@kosli.com via Slack Mintlify session: slack_1782312553.221939_C0AJTQ5633K --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
1 parent 1518268 commit fe5ad72

1 file changed

Lines changed: 70 additions & 32 deletions

File tree

‎tutorials/rotating_api_keys.mdx‎

Lines changed: 70 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Rotating API keys
33
description: Learn how to rotate Kosli service account API keys with zero downtime.
44
---
55

6-
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.
6+
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.
77

88
<Tip>
99
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.
@@ -25,37 +25,75 @@ When you rotate a service account API key, Kosli:
2525

2626
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.
2727

28-
## Rotate a key from the Kosli web app
29-
30-
1. Log in to Kosli and select the organization that owns the service account.
31-
2. Go to **Settings** → **Service accounts** in the left navigation.
32-
3. Open the service account whose key you want to rotate.
33-
4. Find the key in the **API Keys** list and click **Regenerate**.
34-
5. Choose a grace period for the old key, then confirm.
35-
6. Copy the new key value immediately and store it in your secrets manager — it will not be shown again.
36-
37-
## Rotate a key via the API
38-
39-
You can also rotate keys programmatically, which is useful for automating periodic rotation from your CI or a secrets manager.
40-
41-
```shell
42-
curl -X POST \
43-
-H "Authorization: Bearer <<your-admin-api-key>>" \
44-
-H "Content-Type: application/json" \
45-
-d '{"grace_period_hours": 24}' \
46-
https://app.kosli.com/api/v2/service-accounts/<<your-org>>/<<service-account-name>>/api-keys/<<key-id>>/rotate
47-
```
48-
49-
The response contains the new API key value. Capture it directly into your secrets store:
50-
51-
```shell
52-
NEW_KEY=$(curl -s -X POST \
53-
-H "Authorization: Bearer $KOSLI_ADMIN_TOKEN" \
54-
-H "Content-Type: application/json" \
55-
-d '{"grace_period_hours": 24}' \
56-
https://app.kosli.com/api/v2/service-accounts/$ORG/$SA_NAME/api-keys/$KEY_ID/rotate \
57-
| jq -r '.api_key')
58-
```
28+
## Rotate a key
29+
30+
Choose the interface that best fits your workflow. All three trigger the same rotation flow described above.
31+
32+
<Tabs>
33+
<Tab title="Web UI">
34+
1. Log in to Kosli and select the organization that owns the service account.
35+
2. Go to **Settings** → **Service accounts** in the left navigation.
36+
3. Open the service account whose key you want to rotate.
37+
4. Find the key in the **API Keys** list and click **Regenerate**.
38+
5. Choose a grace period for the old key, then confirm.
39+
6. Copy the new key value immediately and store it in your secrets manager — it will not be shown again.
40+
</Tab>
41+
42+
<Tab title="CLI">
43+
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:
44+
45+
```shell
46+
kosli rotate api-key <<key-id>> \
47+
--service-account <<service-account-name>> \
48+
--grace-period-hours 24 \
49+
--api-token "$KOSLI_ADMIN_TOKEN" \
50+
--org "$ORG"
51+
```
52+
53+
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:
54+
55+
```shell
56+
kosli rotate api-key keyID1 keyID2 \
57+
--service-account <<service-account-name>> \
58+
--api-token "$KOSLI_ADMIN_TOKEN" \
59+
--org "$ORG"
60+
```
61+
62+
Use `--output json` to capture the new key value programmatically:
63+
64+
```shell
65+
NEW_KEY=$(kosli rotate api-key <<key-id>> \
66+
--service-account <<service-account-name>> \
67+
--api-token "$KOSLI_ADMIN_TOKEN" \
68+
--org "$ORG" \
69+
--output json \
70+
| jq -r '.api_key')
71+
```
72+
</Tab>
73+
74+
<Tab title="API">
75+
Call the rotate endpoint directly — useful when integrating with a secrets manager or another automation system:
76+
77+
```shell
78+
curl -X POST \
79+
-H "Authorization: Bearer <<your-admin-api-key>>" \
80+
-H "Content-Type: application/json" \
81+
-d '{"grace_period_hours": 24}' \
82+
https://app.kosli.com/api/v2/service-accounts/<<your-org>>/<<service-account-name>>/api-keys/<<key-id>>/rotate
83+
```
84+
85+
The response contains the new API key value. Capture it directly into your secrets store:
86+
87+
```shell
88+
NEW_KEY=$(curl -s -X POST \
89+
-H "Authorization: Bearer $KOSLI_ADMIN_TOKEN" \
90+
-H "Content-Type: application/json" \
91+
-d '{"grace_period_hours": 24}' \
92+
https://app.kosli.com/api/v2/service-accounts/$ORG/$SA_NAME/api-keys/$KEY_ID/rotate \
93+
| jq -r '.api_key')
94+
```
95+
</Tab>
96+
</Tabs>
5997
6098
<Tip>
6199
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.

0 commit comments

Comments
 (0)