API Key Authentication for the Big Brain Ape REST API

Pass your Big Brain Ape API key in the Authorization header to authenticate every REST API request. Learn how to generate and use API keys.

Every request to the Big Brain Ape API must be authenticated with an API key. You pass your key in the Authorization header using the Bearer scheme. The API validates the key on every request, checks that it has the required scope for the endpoint being called, and — if IP allowlisting is enabled on your key — verifies the originating IP address. Without a valid, in-scope key, the request is rejected before any logic runs.

Never expose your API key in client-side code, public repositories, or anywhere it could be read by a third party. Anyone who obtains your key can take actions on your account up to the permissions granted by that key’s scopes. If a key is compromised, revoke it immediately from the dashboard and generate a new one.

Getting an API key

1. Open your account settings

   Click your avatar in the top-right corner of the dashboard and select Settings.

2. Navigate to API Keys

   Select the API Keys tab in the left sidebar of the Settings page.

3. Create a new key

   Click Generate New Key, give it a descriptive name, choose the scopes it needs, and optionally restrict it to specific IP addresses.

4. Copy and store the key securely

   The secret value is shown only once. Copy it into a password manager or secrets vault before closing the dialog.

For a full walkthrough including scope selection and IP allowlisting, see the API Keys security guide.

Making authenticated requests

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

curl -X GET https://api.bigbrainape.com/v1/portfolio \
  -H "Authorization: Bearer bba_sk_live_abc123xyz"

The same pattern applies in any language or HTTP client:

Python

import requests

API_KEY = "bba_sk_live_abc123xyz"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.get(
    "https://api.bigbrainape.com/v1/portfolio",
    headers=headers,
)

data = response.json()
print(data)

Store your API key in an environment variable (for example, BBA_API_KEY) rather than hardcoding it in your source files. Read it at runtime with process.env.BBA_API_KEY (Node.js) or os.environ["BBA_API_KEY"] (Python).

Key scopes

When you generate a key you assign it one or more scopes that control which endpoints it can call:

Scope	What it allows
read	Read-only access to portfolio, market data, and alert listings
trade	Submit and cancel swap orders
alerts	Create, update, and delete alerts
all	Full access to every endpoint

If you call an endpoint with a key that lacks the required scope, the API returns a 403 Insufficient Scope error. Always use the most restrictive scope that your integration actually needs.

Authentication errors

Error Code	HTTP Status	Meaning
MISSING_TOKEN	401	The Authorization header was not included in the request
INVALID_TOKEN	401	The key was not found, has been revoked, or is malformed
INSUFFICIENT_SCOPE	403	The key exists but does not have permission for this endpoint
IP_NOT_ALLOWED	403	The request originated from an IP address not on the key’s allowlist

Managing API keys programmatically

In addition to creating and revoking keys in the dashboard, you can manage them through the API itself. Both endpoints require an existing key with the all scope.

GET /auth/api-keys

Returns a list of all API keys on your account (secret values are never returned — only metadata).

curl -X GET https://api.bigbrainape.com/v1/auth/api-keys \
  -H "Authorization: Bearer bba_sk_live_abc123xyz"

Response:

{
  "success": true,
  "data": [
    {
      "id": "key_abc123",
      "label": "Trading bot",
      "scopes": ["trade", "read"],
      "ipAllowlist": ["203.0.113.0/24"],
      "createdAt": "2024-01-10T09:00:00Z",
      "lastUsedAt": "2024-01-15T14:32:00Z"
    }
  ],
  "timestamp": "2024-01-15T14:35:00Z"
}

id · string

Unique identifier for the API key.

label · string

Human-readable name you set when creating the key.

scopes · array

List of permission scopes assigned to this key.

ipAllowlist · array

IP addresses or CIDR ranges allowed to use this key. Empty array means no restriction.

createdAt · string

ISO 8601 timestamp of when the key was created.

lastUsedAt · string

ISO 8601 timestamp of the most recent authenticated request. null if never used.

POST /auth/api-keys

Creates a new API key. The secret value is returned only in this response — store it immediately.

curl -X POST https://api.bigbrainape.com/v1/auth/api-keys \
  -H "Authorization: Bearer bba_sk_live_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Alerts automation",
    "scopes": ["alerts", "read"],
    "ipAllowlist": ["203.0.113.42"]
  }'

label · string · required

A descriptive name for the key (e.g., "Trading bot", "Alerts automation").

scopes · array · required

Array of permission scopes: read, trade, alerts, or all.

ipAllowlist · array

Optional list of IPv4/IPv6 addresses or CIDR ranges. Omit to allow requests from any IP.

Response:

{
  "success": true,
  "data": {
    "id": "key_xyz789",
    "label": "Alerts automation",
    "secret": "bba_sk_live_xyz789...",
    "scopes": ["alerts", "read"],
    "ipAllowlist": ["203.0.113.42"],
    "createdAt": "2024-01-15T14:35:00Z"
  },
  "timestamp": "2024-01-15T14:35:00Z"
}

The secret field is returned only once in this response. Copy it to a secure location immediately — it cannot be retrieved again. If you lose it, revoke the key and create a new one.