Search⌘K
Agent API › Getting Started › Authentication

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

Sign in to BLACKBOX

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

Upgrade to Pro

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

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

BLACKBOX_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxx
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.