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 "$BOX_API_KEY" --json

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. Manage key lifecycle with box api-key list|rotate|revoke or in the dashboard 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. 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 Secrets & Setup.

​Create a key

​Store keys

​Rotate a key

​Delete a key

​Use the key

Create a key

Store keys

Rotate a key

Delete a key

Use the key