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

# Sandbox API key scopes

> Choose sandbox API key scopes for CI credentials and inspect key metadata for account access.

Choose sandbox API key scopes to limit a bead credential for CLI, API, SDK, or headless MCP access. Keep the secret in private storage.

## Create a CI key

The shipped CLI key creation preset is `ci`:

```bash theme={null}
bead api-key create ci --preset ci --ttl 90d
```

Creation requires admin scope. CI keys can create machines, execute commands and file operations, and delete their own machines. They cannot administer profiles, billing, accounts, or CI configuration. TTL ranges from 60 seconds to 90 days and accepts seconds (`s`), hours (`h`), or days (`d`). Store returned credential material directly in your CI secret store and keep it out of job logs. See [Run CI on bead](https://docs.bead.run/ci/portable.md).

## Use a key

The CLI reads `BEAD_API_KEY`, or a private file selected by `BEAD_API_KEY_FILE`. Saved files default to `~/.config/bead/credentials.json`, subject to `XDG_CONFIG_HOME`.

REST calls can send a key in the API key header:

```bash theme={null}
curl -fsSL https://api.bead.run/v1/limits   -H "X-API-Key: $BEAD_API_KEY"
```

Headless MCP clients send `Authorization: Bearer` on every request. A session ID does not authorize a request. See [MCP authentication](https://docs.bead.run/mcp/connect.md).

## Inspect key metadata

With admin scope:

```bash theme={null}
bead api GET /api-keys
```

The metadata list does not recover an existing plaintext secret. Check recorded scope and expiry before assigning a key to automation.

## Scopes

`read`, `write`, and `admin` are independent permissions. The `use` scope permits supported mutations of existing machines without creation, snapshot/fork, or account administration; `write` also permits operations that require `use`. Admin-scoped customer operations include ownership, membership, and billing controls. A delegated token cannot exceed the source credential's authority.

An optional [key budget](https://docs.bead.run/platform/key-budgets.md) can further restrict funded work. Expiry or rejected scope requires an appropriate valid credential; changing a client header does not expand permissions.


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