API Keys - ascii

Use a Box API key for servers, CI jobs, Docker images, and hosted workers. API keys authenticate Box operations without an interactive browser flow.

Treat API keys as secrets. Store them in your platform secret manager and pass them at runtime as BOX_API_KEY. Do not commit them, print them in logs, or bake them into Docker images.

Create a key

Create one key per project so you can rotate or revoke each independently. From the CLI:

box api-key create my-project

The secret is shown once. The backend stores only a hash and can never show it again, so save it immediately. In scripts and agents, add --json and read .secret:

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

Or use the dashboard:

Open the Box dashboard.
Go to API Keys.
Create a key.
Copy the secret immediately. The dashboard shows it only once.

Creating, rotating, and revoking keys requires a browser sign-in session: box login without a key, or the dashboard. A CLI or API client authenticated with an API key can use Box normally but cannot manage keys.

Use the copied value as BOX_API_KEY in your runtime environment:

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)

The CLI login emits:

{
  "event": "login_complete",
  "data": {
    "user": {
      "login": "octocat",
      "email": "octocat@example.com"
    }
  }
}

For scripts, prefer --json on login too. It keeps stdout machine-readable and makes failed auth return the standard JSON error line.

List your keys

Listing is the one key operation available on every surface. Secrets are never returned. Each row includes the id, name, prefix, last four characters, 30-day request total, and how many Boxes and Agents that key created that still exist.

box api-key list
box api-key list --all    # include the per-box machine keys the platform manages

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

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

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 is CLI and dashboard only. There is no public API endpoint for them, so no SDK method either: a credential that could mint more credentials would defeat the point. Use box api-key create|rotate|revoke after a browser sign-in, or the API Keys tab.

Store keys

Use the secret manager for your platform:

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. 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.
Delete the old key after the new deployment is live.

Delete a key

Deleting a key immediately revokes 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. Delete keys that are unused, leaked, or no longer tied to an active deployment with box api-key revoke <id> or from the dashboard API Keys tab.

Use the key

For Docker and hosted workers, see Use in Docker. For scripts and applications that wrap the CLI, see Use in Code. For runtime secrets inside Boxes, see Environments.

​Create a key

​List your keys

​See usage for one key

​Store keys

​Rotate a key

​Delete a key

​Use the key

Create a key

List your keys

See usage for one key

Store keys

Rotate a key

Delete a key

Use the key