Docs · Accounts

API keys and scopes

Scripts, CI and agents use API keys. Give each key only what it needs: a key has a set of actions, and can be limited to some sandboxes, by name or by label. A request is allowed only when its action is on the key and, for a request about one sandbox, that sandbox is on the key (or the key created it) and has the key's labels. Anything else gets 403 api_key_action_forbidden or 403 api_key_sandbox_forbidden.

$ froog api-key create ci-bot --preset ci --ttl 30d          # prints the key once
$ froog api-key create watcher --preset read-only
$ froog api-key create box-agent --sandbox my-box            # everything on my-box, nothing else
$ froog api-key create team-a --preset ci --label team=a     # only sandboxes labelled team=a
$ froog api-key create ci-bot --preset ci --env ci           # only sandboxes of the ci environment
$ froog api-key create custom --actions sandbox.read,exec,file.read --ttl 7d
$ froog api-key list                                          # scope, expiry, last use, requests in 30 days, sandboxes it created
$ froog api-key rotate key_3f2a9c1d8e7b                       # new secret, same id, scope and expiry
$ froog api-key revoke key_3f2a9c1d8e7b
$ froog api-key actions                                       # every action and preset

Preset	Can
`read-only`	Inspect sandboxes, their history and processes, files, snapshots and the environment.
`full-sandbox`	Operate sandboxes: exec, prompt, files, SSH, desktop, public URLs, snapshots, stop, rename. Not create, start, fork or delete, and no account changes.
`ci`	`full-sandbox`, plus create, start and fork, and delete the sandboxes this key created.
`admin`	Everything, including billing, webhooks and creating more keys.

Actions: sandbox.create, sandbox.read, sandbox.update, sandbox.stop, sandbox.resume, sandbox.fork, sandbox.delete, sandbox.delete-own, agent.prompt, exec, file.read, file.write, ssh, desktop, host, snapshot.read, snapshot.write, environment.read, environment.write, account.read, account.admin, inbox.read, inbox.write (email inboxes; the key inside a sandbox has both, for the inbox attached to it only), billing.trial (read billing and start the free trial, nothing else, account.admin includes it), and * for everything.

The key inside each sandbox. Every sandbox has the froog CLI, signed in with a key that reaches only that sandbox, so the agents in it can run froog host "$(hostname)" 3000, take snapshots or stop it. It can read, rename and stop the sandbox, exec, prompt, read and write files, SSH, open the desktop, host ports and read and save snapshots. It can't create, start, fork or delete sandboxes, reach other sandboxes, or change the account. It is replaced at every start and revoked when the sandbox stops or is deleted, and it isn't listed in froog api-key list. A sandbox created with --no-environment gets no key.

Every key expires: 90 days by default, at most 365, or --ttl never. An expired key gets 401 api_key_expired.
A key that can create keys (account.admin) can't create one with more actions, more sandboxes, fewer labels or a later expiry than its own. Approving an froog login needs the dashboard or a full key.
A key limited to sandboxes lists only those (plus the ones it created), and sees no API keys or audit log.
A key limited by environment (froog api-key create ci-bot --preset ci --env ci, repeat --env for several, API environments) reaches only sandboxes of those environments, in lists too, and sees only those environments. What it creates goes into its first environment unless it names another of its own. Naming any other gets 403 api_key_environment_forbidden, for forks and starts too. Like any limited key it can't change environments (environment.write), and a key it creates must be limited to its environments or fewer.
A key limited by labels (--label KEY=VALUE, repeat for several, API labels) reaches only sandboxes that have all of them, in lists too. Sandboxes it creates or forks get its labels, and asking for another value of one gets 403 api_key_label_forbidden, as does changing or removing those labels on a sandbox. A key it creates must have at least its labels. The MCP endpoint checks the same way.
Keys made before scopes, and dashboard keys with Everything, have full access. The CLI asks for a scope, and full access needs --preset admin.
Revoking a key stops it at once, but sandboxes it created stay.
Rotating gives a key a new secret and stops the old one at once. Its id, scope and expiry stay. An expired key can't be rotated (409 api_key_expired): create a new one. For no downtime, create a new key, deploy it, then revoke the old one.