Skip to main content
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'
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 CodeErrorCause
401UnauthorizedAPI key is missing, malformed, or invalid
403ForbiddenAPI 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.