> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Rotate a key

Last updated 12 November 2026

Replace an API key with a new one without stopping the program that uses it: create the next key, give it to the program, then revoke the old one. A key is never changed in place, so a new narrowing or a new expiry is also a rotation.

## Find the key {#find}

In the console, open **API keys**. With the CLI or the API:

**CLI**

```shell
tonbo api-key list
```

**API**

```shell
curl -sS https://api.tonbo.dev/v1/api-keys \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

Note its id, the member it acts as and its narrowing. You see your own keys; owners and admins see every key of the account.

## Create the next key {#create}

In the console, choose **New API key** on **API keys**, and pick the same member under **Acts as**, the same **Access**, **Databases** and **Streams**, and an **Expires**. With the CLI or the API, name the same member and narrowing under a new name, since a live key’s name is unique:

**CLI**

```shell
tonbo api-key create report-job-2 --member report-job --database reports --expires-in 6_months
```

**API**

```shell
curl -sS https://api.tonbo.dev/v1/api-keys \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"report-job-2","member":"agent.<agent id>","databases":["reports"],"expires_in":"6_months"}'
```

The secret is in this answer only: store it in your secret store now. A key that acts as an Agent is created by an owner or an admin (see [Who manages its keys and its role](https://tonbo.dev/docs/platform/agents.md#agent-keys)).

## Give it to the program {#deploy}

Put the new secret where the program reads its key, such as `TONBO_API_KEY`, and restart it. A program that keeps a token file fresh with the refresher needs the refresher restarted with the new key instead (see [Running the refresher](https://tonbo.dev/docs/platform/api-keys.md#running)). Check that the program works before you go on: both keys work until you revoke the old one.

## Revoke the old key {#revoke}

In the console, choose **Revoke** beside it on **API keys**, then **Revoke key**. With the CLI, which asks you to type `yes` at a terminal, or the API:

**CLI**

```shell
tonbo api-key revoke <old key id>
```

**API**

```shell
curl -sS -X DELETE https://api.tonbo.dev/v1/api-keys/<old key id> \
  -H "Authorization: Bearer $TONBO_API_KEY"
```

Revoking stops new exchanges at once, and the tokens already exchanged from the key stop shortly after in every region, at the latest when they expire (see [What a key can reach](https://tonbo.dev/docs/platform/api-keys.md#key-scope)).
