> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ascii.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Create, store, rotate, and revoke Box API keys for automation.

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

<Warning>
  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.
</Warning>

## Create a key

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

```bash theme={null}
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`:

```bash theme={null}
BOX_API_KEY="$(box api-key create my-project --json | jq -r '.secret')"
```

Or use the dashboard:

1. Open the [Box dashboard](https://box.ascii.dev/box/dashboard?tab=api-keys).
2. Go to **API Keys**.
3. Create a key.
4. Copy the secret immediately. The dashboard shows it only once.

<Note>
  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.
</Note>

Use the copied value as `BOX_API_KEY` in your runtime environment:

<CodeGroup>
  ```bash CLI theme={null}
  box login "$BOX_API_KEY" --json
  ```

  ```bash curl theme={null}
  curl -sS "$BOX_API_BASE/me" \
    -H "Authorization: Bearer $BOX_API_KEY"
  ```

  ```ts TypeScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

The CLI login emits:

```json theme={null}
{
  "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:

1. Rotate the key: `box api-key rotate <id>` (find ids with `box api-key list`), or use 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 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](/box/use-in-production).

For scripts and applications that wrap the CLI, see [Use in Code](/box/use-in-code).

For runtime secrets inside Boxes, see [Secrets & Setup](/box/secrets).