Create and list keys

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.

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.

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. Boat shows the secret one time only. In scripts, capture it like this:

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

boat login --key-stdin --json <<< "$BOAT_API_KEY"

curl -sS "$BOAT_API_BASE/me" \
  -H "Authorization: Bearer $BOAT_API_KEY"

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);

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)

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

boat api-key list
boat api-key list --all    # include per-sandbox machine keys

TypeScript

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

Python

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.

boat api-key usage sak_123
boat api-key usage sak_123 --verbose

​Create a key

​Use the key

​What a key cannot do

​List

​See usage for one key

Create a key

Use the key

What a key cannot do

List

See usage for one key