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.
Prerequisites
- A Kosli shared organization with at least one service account 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.
How rotation works
When you rotate a service account API key, Kosli:
- Generates a new API key immediately and returns its value once.
- Sets the new key’s expiry to the rotated key’s current expiry unless you pass
--expires-at (CLI) or expires_at (API), bounded by the server-side maximum lifetime of 365 days from creation.
- Keeps the old key valid for a configurable grace period (default: 24 hours).
- Automatically revokes the old key when the grace period expires.
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.
Rotation on its own does not extend the credential. If the rotated key is already close to its expiry (for example, most of the way through the 365-day cap), the new key inherits that expiry and dies at the same moment — the exact failure rotation is supposed to prevent. Pass --expires-at to reset the clock, up to the 365-day cap.
Rotate a key
Choose the interface that best fits your workflow. All three trigger the same rotation flow described above.
- Log in to Kosli and select the organization that owns the service account.
- Go to Settings → Service accounts in the left navigation.
- Open the service account whose key you want to rotate.
- Find the key in the API Keys list and click Regenerate.
- Choose a grace period for the old key, then confirm.
- 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 command to rotate one or more keys from your terminal or a CI job:--expires-at accepts an epoch timestamp, YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, or an RFC3339 timestamp, and is capped at 365 days from creation. Omit it to inherit the rotated key’s expiry — combine that with a rotation cadence well inside the 365-day cap, or pass --expires-at to reset the clock.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:Use --output json to capture the new key value programmatically: Call the rotate endpoint directly — useful when integrating with a secrets manager or another automation system:expires_at is an epoch timestamp for the new key’s expiry. Omit it to inherit the rotated key’s expiry. The value is capped at 365 days from creation.The response contains the new API key value. Capture it directly into your secrets store: 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 for details. Roll the new key out
While the old key is still valid, update every consumer to use the new key:
- CI/CD pipelines: Update the
KOSLI_API_TOKEN secret in GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.
- Runtime reporters: Update Kubernetes secrets used by the Kosli Kubernetes reporter, and roll the relevant pods.
- Local config files: Update any Kosli CLI config files that hard-code the token.
- Secrets managers: Update the value in AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, Azure Key Vault, or wherever you store the token.
Verify the rollout by triggering a job (or running a Kosli CLI command) that uses the new key and confirming it succeeds:
Verify the old key is decommissioned
Once every consumer is on the new key, you can either wait for the grace period to elapse or revoke the old key immediately:
See Revoke an API key for a service account for details.
After revocation (or grace-period expiry), confirm the old key no longer works:
Recommended rotation cadence
- Service accounts: rotate at least every 90 days, and immediately if you suspect a leak.
- After offboarding: rotate any key an offboarded user could have accessed.
- After incidents: rotate any key potentially exposed by a security incident, regardless of cadence.
Automating rotation from your secrets manager — using the rotate endpoint above — is the most reliable way to keep within your target cadence.
