> ## 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.

# API keys and tokens

> Create scoped, expiring boat API keys, use them as bearer tokens, and revoke a leaked key.

Create a key for CI or a server:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
boat api-key create ci --preset ci --ttl 90d
```

Store the secret as `BOAT_API_KEY`. Send it as a bearer token:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl -sS https://boat.dev/api/v1/me -H "Authorization: Bearer $BOAT_API_KEY"
```

* A new key starts with `boat_`. Older keys start with `box_` and still work.
* Every new key expires. The maximum is 365 days.
* Every new key has a scope. boat checks it on each request.
* A key acts as you. It is either an **organization key** or an **account key**.

| Key | Made from | Bills and sees | Account settings |
| - | - | - | - |
| Organization key | The dashboard with that organization selected, `boat --org <org> api-key create`, `boat api-key create` while that organization is active, or `"org": "<org>"` (or `X-Boat-Org: <org>`) on `POST /api-keys/scoped` | That organization only. A request that names another organization or Personal gets `403 api_key_org_mismatch`. | Refused (`403 api_key_org_forbidden`): webhooks, AI credentials, billing, keys, members. |
| Account key | The dashboard with Personal selected, `boat --org personal api-key create`, or a request that names no organization | The organization a request names with `X-Boat-Org: <org>`, else your active wallet. Read [Active wallet](https://docs.boat.dev/organizations/active-wallet.md). | Allowed, if the scope allows it. |

The dashboard lists the keys of the selected organization. Personal lists the account keys.

> [!WARNING]
>
> A key leaked? Revoke it now. Read [Key leaked](https://docs.boat.dev/api-keys/store-rotate-revoke.md#key-leaked).

> [!WARNING]
>
> Treat API keys as secrets. Do not commit them, print them in logs or put them into images.

## Main task

1. [Create a key](https://docs.boat.dev/api-keys/create-and-list.md#create-a-key) with the smallest scope that does the job.
2. [Store it](https://docs.boat.dev/api-keys/store-rotate-revoke.md#store-a-key) as `BOAT_API_KEY` in your platform secret manager.
3. [Use it](https://docs.boat.dev/api-keys/create-and-list.md#use-the-key) from the CLI, the API or an SDK.
4. [Rotate or revoke it](https://docs.boat.dev/api-keys/store-rotate-revoke.md) when you need to.

## Production guidance

* Use one key per job.
* Use the shortest TTL that works for you.
* Use `read-only` or `ci`. Full account access requires an explicit `--preset admin`.
* Pass at least one of `--preset`, `--actions`, `--sandbox` or `--env`.
* Limit a key to sandboxes or environments with `--sandbox` or `--env` when you can.
* For keys inside your end users' sandboxes, read [Security for platforms](https://docs.boat.dev/security.md).

## Learn more

> [card] [Scopes](https://docs.boat.dev/api-keys/scopes.md)
>
> Actions, presets, the in-sandbox API key and scope errors.

> [card] [Create and list keys](https://docs.boat.dev/api-keys/create-and-list.md)
>
> Create a key, use it, list your keys and see the usage of one key.

> [card] [Store, rotate and revoke](https://docs.boat.dev/api-keys/store-rotate-revoke.md)
>
> Revoke a leaked key, store a key and replace its secret.

> [!NOTE]
>
> Keys created before scoped keys existed have no expiry and full access. Replace them with new scoped keys. `boat api-key list` shows them with no expiry.


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