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
In the console, open API keys. With the CLI or the API:
tonbo api-key listcurl -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
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:
tonbo api-key create report-job-2 --member report-job --database reports --expires-in 6_monthscurl -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).
Give it to the program
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). Check that the program works before you go on: both keys work until you revoke the old one.
Revoke the old key
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:
tonbo api-key revoke <old key id>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).