Skip to main content
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:
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.

​
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:
Headless MCP clients send Authorization: Bearer on every request. A session ID does not authorize a request. See MCP authentication.

​
Inspect key metadata

With admin scope:
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 can further restrict funded work. Expiry or rejected scope requires an appropriate valid credential; changing a client header does not expand permissions.