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

# 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.

<Warning>
  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.
</Warning>

## Getting an API key

<Steps>
  <Step title="Open your account settings">
    Click your avatar in the top-right corner of the dashboard and select **Settings**.
  </Step>

  <Step title="Navigate to API Keys">
    Select the **API Keys** tab in the left sidebar of the Settings page.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

For a full walkthrough including scope selection and IP allowlisting, see the [API Keys security guide](/security/api-keys).

## Making authenticated requests

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

```bash theme={null}
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:

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = "bba_sk_live_abc123xyz";

  const response = await fetch("https://api.bigbrainape.com/v1/portfolio", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
  });

  const data = await response.json();
  console.log(data);
  ```

  ```typescript TypeScript theme={null}
  const API_KEY = "bba_sk_live_abc123xyz";

  interface ApiResponse<T> {
    success: boolean;
    data: T;
    timestamp: string;
  }

  const response = await fetch("https://api.bigbrainape.com/v1/portfolio", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
  });

  const result: ApiResponse<unknown> = await response.json();
  console.log(result);
  ```
</CodeGroup>

<Note>
  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).
</Note>

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

```bash theme={null}
curl -X GET https://api.bigbrainape.com/v1/auth/api-keys \
  -H "Authorization: Bearer bba_sk_live_abc123xyz"
```

**Response:**

```json theme={null}
{
  "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"
}
```

<ResponseField name="id" type="string">Unique identifier for the API key.</ResponseField>
<ResponseField name="label" type="string">Human-readable name you set when creating the key.</ResponseField>
<ResponseField name="scopes" type="array">List of permission scopes assigned to this key.</ResponseField>
<ResponseField name="ipAllowlist" type="array">IP addresses or CIDR ranges allowed to use this key. Empty array means no restriction.</ResponseField>
<ResponseField name="createdAt" type="string">ISO 8601 timestamp of when the key was created.</ResponseField>
<ResponseField name="lastUsedAt" type="string">ISO 8601 timestamp of the most recent authenticated request. `null` if never used.</ResponseField>

### POST /auth/api-keys

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

```bash theme={null}
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"]
  }'
```

<ParamField body="label" type="string" required>
  A descriptive name for the key (e.g., `"Trading bot"`, `"Alerts automation"`).
</ParamField>

<ParamField body="scopes" type="array" required>
  Array of permission scopes: `read`, `trade`, `alerts`, or `all`.
</ParamField>

<ParamField body="ipAllowlist" type="array">
  Optional list of IPv4/IPv6 addresses or CIDR ranges. Omit to allow requests from any IP.
</ParamField>

**Response:**

```json theme={null}
{
  "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"
}
```

<Warning>
  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.
</Warning>