Skip to main content
Use a Box API key for servers, CI jobs, Docker images, and hosted workers. API keys authenticate the Box CLI 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

  1. Open the Box dashboard.
  2. Go to API Keys.
  3. Create a key.
  4. Copy it immediately. The dashboard only shows the secret once.
Use the copied value as BOX_API_KEY in your runtime environment: 
box login "$BOX_API_KEY" --json
That 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.

​
Store keys

Use the secret manager for your platform:
PlatformStore as
RailwayVariable named BOX_API_KEY
GitHub ActionsRepository or environment secret named BOX_API_KEY
Docker ComposeEnvironment variable or secret named BOX_API_KEY
KubernetesSecret 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:
  1. Rotate the key in the dashboard.
  2. Copy the new secret.
  3. Update BOX_API_KEY in your platform secret manager.
  4. Redeploy or restart workers that use the key.
To avoid downtime, create a second key first:
  1. Create a new key.
  2. Update the platform secret to the new key.
  3. Redeploy or restart workers.
  4. 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.

​
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.