docs: add tutorial on rotating Kosli API keys#229
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Claude finished @vidhu-balad's task in 2m 17s —— View job Review of PR #229 — Rotating API keys tutorial
Overall assessmentGood tutorial — well-structured, correct Diátaxis classification (tutorial), clear writing in active voice, and all required conventions followed. The cross-link from Checklist
FindingsNo critical issues. Three suggestions posted as inline comments:
|
vidhu-balad
changed the title
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| description: Learn how to rotate Kosli service account API keys with zero downtime. | ||
| --- | ||
|
|
||
| ## Introduction |
There was a problem hiding this comment.
Minor: other tutorials in this site (e.g. unauthorized_iac_changes.md) open directly with the intro text after frontmatter, without an ## Introduction heading. Dropping it would be more consistent with the rest of the site.
| ``` | ||
|
|
||
| <Tip> | ||
| 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. |
There was a problem hiding this comment.
The API reference links (this one and the ones in the ## Related section) point to paths generated from the OpenAPI spec. Worth verifying these resolve correctly in the preview deployment before merging — there are no local files backing them.
There was a problem hiding this comment.
All the reference links resolve as expected.
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
| description: Learn how to rotate Kosli service account API keys with zero downtime. | ||
| --- | ||
|
|
||
| ## Introduction |
There was a problem hiding this comment.
Suggestion: Most tutorials in this site (e.g. unauthorized_iac_changes.md, attest_snyk.md, report_aws_envs.md) open directly with intro text after frontmatter — no ## Introduction heading. Only organizing_with_spaces.mdx also uses one. Dropping it would be more consistent with the majority pattern.
| ## Introduction |
|
|
||
| ## Prerequisites | ||
|
|
||
| - A Kosli shared organization with at least one [service account](/getting_started/service-accounts#service-accounts) and an existing API key. |
There was a problem hiding this comment.
Improvement: Both "shared organization" and "service account" link to the same anchor (/getting_started/service-accounts#service-accounts). The link text "shared organization" is misleading — that anchor covers the Service Accounts heading, not shared orgs specifically. Consider simplifying the prerequisite:
| - 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](/getting_started/service-accounts#service-accounts) and an existing API key. |
|
|
||
| 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. |
There was a problem hiding this comment.
Suggestion: CLAUDE.md lists <Steps> / <Step> as the recommended component for sequential procedures. This numbered list would be a good candidate for that component, matching how other tutorials present step-by-step workflows.
| ``` | ||
|
|
||
| <Tip> | ||
| 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. |
There was a problem hiding this comment.
Improvement: The API reference links (/api-reference/service-accounts/...) are generated from the OpenAPI spec and can't be verified locally. Worth confirming they resolve in the preview deployment before merging.
| 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. | ||
|
|
There was a problem hiding this comment.
Improvement: This sequential procedure is a good candidate for the <Steps>/<Step> component, which is used for similar workflows in other tutorials (e.g., report_cloud_run_envs.md, linking_trails_across_branches.md) and recommended in CLAUDE.md for sequential procedures.
| 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. | |
| <Steps> | |
| <Step> | |
| Log in to Kosli and select the organization that owns the service account. | |
| </Step> | |
| <Step> | |
| Go to **Settings** → **Service accounts** in the left navigation. | |
| </Step> | |
| <Step> | |
| Open the service account whose key you want to rotate. | |
| </Step> | |
| <Step> | |
| Find the key in the **API Keys** list and click **Regenerate**. | |
| </Step> | |
| <Step> | |
| Choose a grace period for the old key, then confirm. | |
| </Step> | |
| <Step> | |
| Copy the new key value immediately and store it in your secrets manager — it will not be shown again. | |
| </Step> | |
| </Steps> |
vidhu-balad
changed the title
…orial Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
| 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. | ||
|
|
There was a problem hiding this comment.
Suggestion: The "Rotate a key from the Kosli web app" procedure (lines 30-36) is a sequential numbered list — a good candidate for the <Steps>/<Step> component, which CLAUDE.md recommends for sequential procedures and other tutorials use (report_cloud_run_envs.md, linking_trails_across_branches.md).
| 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. | |
| <Steps> | |
| <Step> | |
| Log in to Kosli and select the organization that owns the service account. | |
| </Step> | |
| <Step> | |
| Go to **Settings** → **Service accounts** in the left navigation. | |
| </Step> | |
| <Step> | |
| Open the service account whose key you want to rotate. | |
| </Step> | |
| <Step> | |
| Find the key in the **API Keys** list and click **Regenerate**. | |
| </Step> | |
| <Step> | |
| Choose a grace period for the old key, then confirm. | |
| </Step> | |
| <Step> | |
| Copy the new key value immediately and store it in your secrets manager — it will not be shown again. | |
| </Step> | |
| </Steps> |
| Automating rotation from your secrets manager — using the rotate endpoint above — is the most reliable way to keep within your target cadence. | ||
|
|
||
| ## Related | ||
|
|
There was a problem hiding this comment.
Suggestion: No other tutorial in the site has a ## Related section. The links are useful, but for consistency you could move them into a <Card>/<CardGroup> at the bottom (matching the navigational card pattern used elsewhere), or simply drop the section since the API reference links are already inline in the body.
| <Tip> | ||
| 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. | ||
| </Tip> |
There was a problem hiding this comment.
Suggestion: The tip on lines 8-10 is nearly identical to the one already on /getting_started/service-accounts (line 31-33). Since the tutorial already links to that page, consider removing it here to avoid maintaining the same statement in two places. If you want to keep a reminder, a shorter inline note ("Remember, the key is shown only once") might be lighter.
2 participants
Adds a new tutorial walking users through zero-downtime rotation of Kosli service account API keys.
Changes
tutorials/rotating_api_keys.mdx— covers how rotation works (grace period), rotating via the Kosli web app, rotating via the API (withcurlexamples), rolling the new key out, verifying the old key is decommissioned, and recommended cadence.config/navigation.json— adds the new tutorial under the existing Tutorials → Security group.