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

# Create and list keys

> Create a scoped Boat API key, use it, list your keys and see the usage of one key.

## Create a key

To create a key, you need one of these:

* A browser session: `boat login` with no key, or the dashboard.
* A token that is already admin-scoped.

The create endpoint is `POST /api/v1/api-keys/scoped`.

<Note>
  During a credential rollout, Boat can turn off key creation for a short time. `GET /api/v1/api-keys` reports this in `catalog.scopedCreationEnabled`. While creation is off, the create endpoint returns a typed 503.
</Note>

```bash theme={null}
boat api-key create my-project --ttl 90d --preset ci --sandbox bx_123
boat api-key create readonly --ttl 30d --preset read-only
boat api-key create admin --ttl 7d --preset admin
boat api-key create custom --ttl 24h --actions sandbox.read,exec,file.read
```

| Flag | Rule |
| - | - |
| `--ttl` | The maximum is 365 days. |
| `--sandbox`, `--env` | You can give each one more than one time. |
| `--actions`, `--preset` | Use one or the other, not both. |
| No `--actions` and no `--preset` | The key is admin-scoped with a 90-day TTL. |

For the actions and presets, read [Scopes](/api-keys/scopes).

Boat shows the secret one time only. In scripts, capture it like this:

```bash theme={null}
BOAT_API_KEY="$(boat api-key create my-project --preset ci --ttl 90d --json | jq -r '.secret')"
```

You can also use the **API Keys** tab in the dashboard. It has expiry presets, action presets, a raw action picker, and sandbox and environment selectors.

## Use the key

<CodeGroup>
  ```bash CLI theme={null}
  boat login --key-stdin --json <<< "$BOAT_API_KEY"
  ```

  ```bash curl theme={null}
  curl -sS "$BOAT_API_BASE/me" \
    -H "Authorization: Bearer $BOAT_API_KEY"
  ```

  ```ts TypeScript theme={null}
  import { BoatApi, Configuration } from "@boatdev/sdk";

  const sandbox = new BoatApi(new Configuration({
    basePath: "https://boat.dev/api/v1",
    accessToken: process.env.BOAT_API_KEY!,
  }));

  const me = await sandbox.me();
  console.log(me.user.login);
  ```

  ```python Python theme={null}
  import os
  from boat_sdk import ApiClient, Configuration
  from boat_sdk.api.boat_api import BoatApi

  config = Configuration(host="https://boat.dev/api/v1", access_token=os.environ["BOAT_API_KEY"])
  with ApiClient(config) as client:
      sandbox = BoatApi(client)
      me = sandbox.me()
      print(me.user.login)
  ```
</CodeGroup>

## What a key cannot do

* Rotate and revoke need a browser session.
* Create needs a browser session or an admin-scoped token. A credential that can make more credentials defeats least privilege.
* To approve an agent claim, you need a browser session. API keys cannot approve agent claims. This includes admin keys and legacy keys.

Use `boat api-key create|rotate|revoke` after a browser sign-in, or use the [API Keys](https://boat.dev/dashboard?tab=api-keys) tab.

## List

Every surface can list keys. This is the only key operation that every surface can do. Boat never returns the secrets.

Each row shows:

* The id, the name, the prefix and the last four characters
* The scope and the expiry
* The last use
* The request total for the last 30 days
* How many sandboxes and Agents the key created that still exist

Boat labels expired keys and keys that expire soon.

Restricted API keys get an empty `apiKeys` list. Only a browser or CLI session, or an unrestricted account key, gets the account-wide list.

```bash theme={null}
boat api-key list
boat api-key list --all    # include per-sandbox machine keys
```

```ts TypeScript theme={null}
const keys = await sandbox.apiKeys();
for (const key of keys.apiKeys) {
  console.log(key.id, key.name, key.usage.requests, key.resources.total);
}
```

```python Python theme={null}
keys = sandbox.api_keys()
for key in keys.api_keys:
    print(key.id, key.name, key.usage.requests, key.resources.total)
```

## See usage for one key

`boat api-key usage <id>` prints the 30-day request total and the count of live resources. These are the same numbers as in the list.

* Add `--verbose` to see the split between sandboxes and Agents, and the list of created resources.
* The matching API is `GET /api-keys/{id}/usage`.
* Usage still works after you revoke the key, if you still have the id.

Revoke stops the secret. It does not delete the sandboxes or Agents that the key created.

```bash theme={null}
boat api-key usage sak_123
boat api-key usage sak_123 --verbose
```


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