# Rotate an API key

> Replace a personal or service API key with a one-time secret and a bounded overlap, while preserving its scopes, repository restrictions and expiry.

Source: https://skaas.io/docs/key-rotation
Last updated: 2026-11-15

## Rotate in the dashboard

Open **Settings → Tokens and MCP setup → Rotate a key**. Choose a key and an overlap from 0 to 86400 seconds. The default is 300 seconds. Zero makes the old key expire immediately.

Copy the replacement secret from the result. It appears once. Replace the key in each assistant, CI job or other client before the displayed overlap deadline. The old key expires at the earlier of its original expiry and the deadline. The replacement preserves scopes, repository restrictions and the original expiry. Rotation does not extend the key's lifetime.

You can rotate your own personal key. An administrator or owner can rotate an organization service key. An administrator cannot rotate another person's personal key. A key cannot create a replacement with more privilege or a longer lifetime than its own credential permits. Revoked, expired or already-rotated keys are refused with a conflict while their records remain.

## Command line

```sh
skaas key rotate <token-id> --org acme --overlap 300
```

`--json` returns the created-key view, its one-time `secret`, `previous_token_id` and `overlap_expires_at`. Keep this output out of logs. The command does not replace an environment variable or a stored sign-in automatically. Use the replacement for subsequent commands.

The API is `POST /v1/orgs/{org}/tokens/{token_id}/rotate`, with `{ "overlap_s": 300 }`. It requires the `repos:admin` scope. A key name is at most 32 characters when creating a key.
