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
• An active Pro subscription — the Agent API is a Pro feature

Getting Your API Key

1. Sign in to BLACKBOX

   Go to app.blackbox.ai and sign in to your account.

2. Upgrade to Pro

   The Agent API requires a Pro plan. If you are not already on Pro, visit app.blackbox.ai/pricing to upgrade.

3. Click Get an API Key

   On the Agent API page at app.blackbox.ai/agent-api, click the Get an API Key button.

   This will automatically create and initialize your dedicated sandbox environment.

4. Create your API key from the Dashboard

   Once provisioning is complete, you will be redirected to your Dashboard. From there, create an API key — this is the key you will use to authenticate all Agent API requests.

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

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

Using the API Key

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

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxx

Example Request

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.):

.env

BLACKBOX_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxx

Python

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

{ "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

{ "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.

Rotating Your API Key

To rotate a compromised key:

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

Deleting a key immediately invalidates it. Any in-flight requests using the old key will receive a 401 response.

ricing).

Rotating Your API Key

To rotate a compromised key:

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

Deleting a key immediately invalidates it. Any in-flight requests using the old key will receive a 401 response.