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

# Scopes

> What a scoped Boat API key can do: actions, presets, the in-sandbox key and scope errors.

## How Boat checks a request

Boat grants a request only when **both** of these are true:

1. The action is in the action set of the key.
2. The target sandbox is in the sandbox set of the key, or in one of its environments.

The default is deny. Boat refuses unknown routes for scoped keys.

## Snapshots and environments

| You want to | The key needs |
| - | - |
| Create a sandbox from a named snapshot | `sandbox.create` for the destination, and `snapshot.read` access to the source |
| Replace a named snapshot | Access to its existing source, and access to the sandbox that you save |

A destination environment does not give access to snapshots from other environments.

## Actions

| Action | What it unlocks |
| - | - |
| `sandbox.create` | Create a sandbox |
| `sandbox.read` | List and inspect sandboxes |
| `sandbox.update` | Rename, recover, and other sandbox writes |
| `sandbox.stop` | Stop |
| `sandbox.resume` | Resume |
| `sandbox.fork` | Fork |
| `sandbox.delete` | Delete |
| `sandbox.delete-own` | Delete only the sandboxes this key created |
| `agent.prompt` | Prompt the sandbox agent |
| `exec` | Run a command |
| `file.read` / `file.write` | Read or write files |
| `ssh` | SSH, scp, and port forward |
| `desktop` | Desktop stream |
| `host` | Host a port |
| `snapshot.read` / `snapshot.write` | Snapshots |
| `environment.read` / `environment.write` | Environments |
| `account.read` | `/me`, limits, list keys, organization discovery |
| `account.admin` | Billing, teams, webhooks, identities, account writes |
| `*` | Admin wildcard |

## Presets

| Preset | Use |
| - | - |
| `read-only` | Inspect sandboxes, files, snapshots, environments |
| `full-sandbox` | Operate a sandbox without create / resume / fork / delete / account writes |
| `ci` | Everything in `full-sandbox`, plus create, resume, fork, and delete the sandboxes this key created. No account admin |
| `admin` | `*` |

A key keeps the actions that it had when you created it. Resume, SSH and `sandbox.delete-own` joined the `ci` preset later. An older `ci` key does not get them. To get them, create a new `ci` key.

## In-sandbox key

Boat writes a credential into each sandbox. This credential is scoped to **that sandbox** only.

| It can | It cannot |
| - | - |
| Prompt, exec, read and write files | Create, resume, fork or delete sandboxes |
| SSH, desktop, host | Write environments |
| Snapshot its own sandbox | Administer the account |

If an attacker takes control of a sandbox, they get access to that one sandbox only.

## Errors

Scoped keys return typed 403 errors:

| `error` | Meaning |
| - | - |
| `api_key_expired` | The TTL elapsed |
| `api_key_action_forbidden` | The action is not on the key |
| `api_key_sandbox_forbidden` | The sandbox or the environment is not on the key |

The bearer header and the SDK configuration do not change.


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