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

# Authentication

> How to authenticate with the BLACKBOX Agent API using API keys and Bearer tokens.

All Agent API endpoints require a valid BLACKBOX API key passed as a Bearer token in the `Authorization` header.

## Prerequisites

* A BLACKBOX account at [app.blackbox.ai](https://app.blackbox.ai)
* An active **Pro subscription** — the Agent API is a Pro feature

## Getting Your API Key

<Steps>
  <Step title="Sign in to BLACKBOX">
    Go to [app.blackbox.ai](https://app.blackbox.ai) and sign in to your account.
  </Step>

  <Step title="Upgrade to Pro">
    The Agent API requires a Pro plan. If you are not already on Pro, visit [app.blackbox.ai/pricing](https://app.blackbox.ai/pricing) to upgrade.
  </Step>

  <Step title="Click Get an API Key">
    On the Agent API page at [app.blackbox.ai/agent-api](https://app.blackbox.ai/agent-api), click the **Get an API Key** button.

    This will automatically create and initialize your dedicated sandbox environment.
  </Step>

  <Step title="Create your API key from the Dashboard">
    Once provisioning is complete, you will be redirected to your [Dashboard](https://app.blackbox.ai/dashboard). From there, create an API key — this is the key you will use to authenticate all Agent API requests.
  </Step>
</Steps>

Your API key will be in the format: `sk-xxxxxxxxxxxxxxxxxxxxxx`

<Warning>
  Keep your API key secret. Never commit it to source control or expose it in client-side code.
</Warning>

## Using the API Key

Pass your API key as a `Bearer` token in the `Authorization` header on every request:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxx
```

### Example Request

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl 'https://agent.blackbox.ai/api/v1/tasks' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxx'
```

## Environment Variable (Recommended)

Store your key in a `.env` file and load it with your preferred tool (`dotenv`, `direnv`, etc.):

```bash .env theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
BLACKBOX_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxx
```

```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.environ["BLACKBOX_API_KEY"]
```

## Authentication Errors

| Status Code | Error          | Cause                                                    |
| ----------- | -------------- | -------------------------------------------------------- |
| `401`       | `Unauthorized` | API key is missing, malformed, or invalid                |
| `403`       | `Forbidden`    | API key is valid but the account lacks the required plan |

### 401 — Unauthorized

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{ "error": "Unauthorized" }
```

Check that:

* The `Authorization` header is present and formatted as `Bearer <key>`
* The key starts with `sk-` and was copied in full
* The key has not been revoked from your dashboard

### 403 — Forbidden

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{ "error": "Claude Agent requires a Pro subscription. Please upgrade at https://www.blackbox.ai/pricing" }
```

Some endpoints (GitHub integration, Claude Agent tasks) require a **Pro subscription**. Upgrade at [app.blackbox.ai/pricing](https://app.blackbox.ai/pricing).

## Rotating Your API Key

To rotate a compromised key:

1. Go to [app.blackbox.ai/dashboard](https://app.blackbox.ai/dashboard)
2. Delete the old key
3. Generate a new key
4. Update your environment variables and redeploy

<Note>
  Deleting a key immediately invalidates it. Any in-flight requests using the old key will receive a `401` response.
</Note>

ricing).

## Rotating Your API Key

To rotate a compromised key:

1. Go to [app.blackbox.ai/dashboard](https://app.blackbox.ai/dashboard)
2. Delete the old key
3. Generate a new key
4. Update your environment variables and redeploy

<Note>
  Deleting a key immediately invalidates it. Any in-flight requests using the old key will receive a `401` response.
</Note>