> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Store, rotate and revoke

> Where to store a Boat API key, how to replace its secret and how to turn it off.

## Store a key

| Platform | Store as |
| - | - |
| Railway | Variable named `BOAT_API_KEY` |
| GitHub Actions | Repository or environment secret named `BOAT_API_KEY` |
| Docker Compose | Environment variable or secret named `BOAT_API_KEY` |
| Kubernetes | Secret mounted or exposed as `BOAT_API_KEY` |

Do not put API keys in:

* Dockerfiles
* Images
* Source code
* Shell history
* Public CI logs

## Rotate a key

Rotate does these things:

* It revokes the old secret immediately.
* It keeps the id, the scope and the expiry date of the key.
* It replaces the secret and shows the new secret one time only.

Rotate does not extend the lifetime of the key. It does not change a legacy key into a scoped key.

You cannot rotate an expired scoped key. The API returns `409 api_key_expired`. Create a replacement key instead.

Rotate needs a browser session. Read [What a key cannot do](/api-keys/create-and-list#what-a-key-cannot-do).

### Rotate with downtime

Use **Rotate** only when you can update the deployed secret immediately.

1. Rotate the key. Run `boat api-key rotate <id>`, or use the dashboard. To find the id, run `boat api-key list`.
2. Copy the new secret.
3. Update `BOAT_API_KEY` in your platform secret manager.
4. Redeploy or restart the workers that use the key.

### Replace without downtime

1. Create a new key.
2. Update the platform secret to the new key.
3. Redeploy or restart the workers.
4. When the new deployment is live, revoke the old key.

## Revoke a key

Run `boat api-key revoke <id>`, or click **Revoke** in the dashboard. Revoke needs a browser session.

* Revoke turns off the key immediately.
* The next Boat API request with that secret fails with an auth error. This includes existing CLI configs and running processes.
* The sandboxes and Agents that the key created stay.
* `boat api-key usage <id>` still shows their totals.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.