API Keys - ascii

A Box API key authenticates servers, CI, and the in-box CLI. Every new key expires and carries an explicit scope. The bearer header does not change — scope lives on the key, enforced at the Box API boundary.

Treat API keys as secrets. Store them as BOX_API_KEY. Do not commit them, print them in logs, or bake them into images.

Existing keys stay account-wide until you reissue them. Reissue anything that still has no expiry.

Scope

A request is granted only when both are true:

The action is in the key’s action set.
The target box is in the key’s box set, or in one of its environments.

Default deny. Unknown routes are refused for scoped keys. Creating a Box from a named snapshot requires box.create for the destination and snapshot.read access to the source. Replacing a named snapshot requires access to both its existing source and the Box being saved. Selecting a destination environment does not grant access to snapshots from other environments.

Actions

Action	What it unlocks
`box.create`	Create a box
`box.read`	List and inspect boxes
`box.update`	Rename, recover, and other box writes
`box.stop`	Stop
`box.resume`	Resume
`box.fork`	Fork
`box.delete`	Delete
`agent.prompt`	Prompt the box 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 boxes, files, snapshots, environments
`full-box`	Operate a box without create / resume / fork / delete / account writes
`ci`	Create, run, snapshot. No account admin
`admin`	`*`

In-box key

The credential written into a box is scoped to that box. It can prompt, exec, read and write files, SSH, desktop, host, and snapshot itself. It cannot create, resume, fork, or delete boxes, and it cannot write environments or administer the account. A compromised box is one box.

Create a key

Creating a key uses POST /api/box/v1/api-keys/scoped and requires a browser session (box login with no key, or the dashboard) or an already-admin token. During a credential rollout the server may temporarily disable creation; GET /api/box/v1/api-keys reports catalog.scopedCreationEnabled, and the create endpoint returns a typed 503 while it is off.

box api-key create my-project --ttl 90d --preset ci --box bx_123
box api-key create readonly --ttl 30d --preset read-only
box api-key create admin --ttl 7d --preset admin
box api-key create custom --ttl 24h --actions box.read,exec,file.read

--ttl max is 365 days. --box and --env are repeatable. --actions and --preset are mutually exclusive. Omit both and the key is admin-scoped with a 90-day TTL. The secret is shown once. In scripts:

BOX_API_KEY="$(box api-key create my-project --preset ci --ttl 90d --json | jq -r '.secret')"

Or the dashboard API Keys tab: expiry presets, action presets, a raw action picker, and box / environment selectors.

box login --key-stdin --json <<< "$BOX_API_KEY"

curl -sS "$BOX_API_BASE/me" \
  -H "Authorization: Bearer $BOX_API_KEY"

import { BoxApi, Configuration } from "@asciidev/box-sdk";

const box = new BoxApi(new Configuration({
  basePath: "https://ascii.dev/api/box/v1",
  accessToken: process.env.BOX_API_KEY!,
}));

const me = await box.me();
console.log(me.user.login);

import os
from ascii_box_sdk import ApiClient, Configuration
from ascii_box_sdk.api.box_api import BoxApi

config = Configuration(host="https://ascii.dev/api/box/v1", access_token=os.environ["BOX_API_KEY"])
with ApiClient(config) as client:
    box = BoxApi(client)
    me = box.me()
    print(me.user.login)

Rotate and revoke stay session-gated. Approving an agent claim also requires a browser session. API keys, including admin and legacy keys, cannot approve agent claims.

List

Listing is the one key operation available on every surface. Secrets are never returned. Each row includes the id, name, prefix, last four characters, scope, expiry, last used, 30-day request total, and how many Boxes and Agents that key created that still exist. Expired and expiring keys are labeled. Restricted API keys receive an empty apiKeys list; the account-wide inventory is returned only to a browser/CLI session or an unrestricted account key.

box api-key list
box api-key list --all    # include per-box machine keys

TypeScript

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

Python

keys = box.api_keys()
for key in keys.api_keys:
    print(key.id, key.name, key.usage.requests, key.resources.total)

See usage for one key

box api-key usage <id> prints the same 30-day request total and live resource count. Add --verbose for the Boxes/Agents split and the created resource list. GET /api-keys/{id}/usage is the matching API. Usage still works after you revoke the key, as long as you still have the id. Revoking stops the secret. It does not delete Boxes or Agents the key created.

box api-key usage sak_123
box api-key usage sak_123 --verbose

Creating, rotating, and revoking keys stay session-gated, except that an admin-scoped token can create a new key. A credential that could mint more credentials would defeat the point of least privilege. Use box api-key create|rotate|revoke after a browser sign-in, or the API Keys tab.

Errors

Scoped keys return typed 403s:

`error`	Meaning
`api_key_expired`	TTL elapsed
`api_key_action_forbidden`	Action not on the key
`api_key_box_forbidden`	Box or environment not on the key

The bearer header and SDK config are unchanged.

Store keys

Platform	Store as
Railway	Variable named `BOX_API_KEY`
GitHub Actions	Repository or environment secret named `BOX_API_KEY`
Docker Compose	Environment variable or secret named `BOX_API_KEY`
Kubernetes	Secret mounted or exposed as `BOX_API_KEY`

Do not put API keys in:

Dockerfiles
Images
Source code
Shell history
Public CI logs

Rotate a key

Rotating a key immediately revokes the old secret, preserves the API key id, and shows a new secret once. An expired scoped key cannot be rotated; the API returns 409 api_key_expired, so create a replacement instead. Use Rotate only when you can update the deployed secret immediately:

Rotate the key: box api-key rotate <id> (find ids with box api-key list), or use the dashboard.
Copy the new secret.
Update BOX_API_KEY in your platform secret manager.
Redeploy or restart workers that use the key.

To avoid downtime, create a second key first:

Create a new key.
Update the platform secret to the new key.
Redeploy or restart workers.
Revoke the old key after the new deployment is live.

Revoke a key

Revoking a key immediately disables it. Existing CLI configs or running processes using that key will fail the next Box API request with an auth error. Boxes and Agents that key created stay. box api-key usage <id> still shows their totals. Do not put keys in Dockerfiles, images, source, shell history, or public CI logs. Production guidance: one key per job, shortest TTL you can live with, read-only or ci unless you truly need admin. Reissue legacy keys.

Rotate and revoke

Rotate keeps the id, scope, and expiry date, replaces the secret, and shows the new secret once. It does not extend the key’s lifetime or convert a legacy key into a scoped key. To avoid downtime, create a second key, cut over, then revoke the old one. box api-key revoke <id> or Revoke in the dashboard. The next request with that secret fails auth.

​Scope

​Actions

​Presets

​In-box key

​Create a key

​List

​See usage for one key

​Errors

​Store keys

​Rotate a key

​Revoke a key

​Rotate and revoke

Scope

Actions

Presets

In-box key

Create a key

List

See usage for one key

Errors

Store keys

Rotate a key

Revoke a key

Rotate and revoke