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

# Big Brain Ape API Keys: Create, Manage, and Rotate

> Learn how to generate scoped API keys on Big Brain Ape, configure IP allowlists, set the right permissions, and rotate or revoke keys securely.

API keys let you connect trading bots, analytics tools, and custom scripts to your Big Brain Ape account without exposing your login credentials. Each key carries a specific set of permissions — called scopes — so you can give an integration exactly the access it needs and nothing more. You can create multiple keys, restrict them to known IP addresses, and revoke any key instantly if it is ever compromised.

<Note>
  Two-factor authentication must be enabled on your account before you can create or delete API keys. See the [Two-Factor Auth guide](/security/two-factor-auth) to get set up.
</Note>

## Key permissions (scopes)

When you create an API key you choose which scopes to grant. Assign the minimum permissions required for your use case.

| Scope | What it allows |
| - | - |
| `read` | Read portfolio balances, market data, and trade history. No write access of any kind. |
| `trade` | Execute buy and sell orders on your behalf. Combine with `read` for most trading bots. |
| `alerts` | Create and delete price and portfolio alerts. Does not grant trading access. |
| `all` | Full access across all scopes. Suitable for development environments only — avoid using `all` for production automated scripts. |

## Creating an API key

<Steps>
  <Step title="Open API Keys settings">
    Go to **Settings → API Keys**. You'll see a list of all your existing keys along with their scopes and last-used timestamps.
  </Step>

  <Step title="Start a new key">
    Click **New API Key** to open the key creation form.
  </Step>

  <Step title="Enter a label">
    Give the key a descriptive label that identifies where it will be used — for example, `trading-bot-prod` or `portfolio-dashboard`. This label appears in your activity log, making it easy to trace which key performed any given action.
  </Step>

  <Step title="Select permissions">
    Check the scopes your integration needs. Avoid selecting `all` unless you are testing locally. For a read-only dashboard, select only `read`. For an automated trading script, select `read` and `trade`.
  </Step>

  <Step title="Set an IP allowlist (optional)">
    Enter one or more IP addresses or CIDR ranges that are allowed to use this key. Requests from any other IP will be rejected. Leave this field empty if your integration runs from a dynamic IP address.
  </Step>

  <Step title="Confirm with 2FA">
    Enter the current 6-digit code from your authenticator app and click **Create Key**.
  </Step>

  <Step title="Copy your key immediately">
    Your new API key is displayed exactly once. Copy it now and store it securely — for example, in your deployment environment's secrets manager or an encrypted vault. After you close this dialog, the full key cannot be retrieved again.
  </Step>
</Steps>

<Warning>
  The API key is shown **only once** at the moment of creation. If you close the dialog without copying it, you must revoke the key and create a new one. Big Brain Ape cannot recover or display the key again.
</Warning>

## IP restrictions

Adding an IP allowlist to a key means it will only work when requests originate from the addresses you specify. This protects you in the event the key is leaked — an attacker would also need to be on your allowed network to use it.

You can enter:

* A single IPv4 address, e.g. `203.0.113.42`
* An IPv6 address, e.g. `2001:db8::1`
* A CIDR range, e.g. `203.0.113.0/24`
* Multiple entries by adding one per line

To update the IP allowlist on an existing key, revoke it and create a replacement — the allowlist cannot be edited after creation.

## Rotating a key

Rotate your API keys regularly to limit the damage of any undetected exposure. Follow these steps to rotate without downtime:

1. **Create a replacement key** with the same scopes and IP restrictions as the key you're replacing. Copy the new key value.
2. **Update your integration** to use the new key. Deploy and verify that the integration is working correctly with the new key.
3. **Revoke the old key** once you have confirmed the replacement is live (see the section below).

This order — create, update, then revoke — ensures your integration is never without a valid key during the transition.

<Tip>
  Label your keys with a version suffix (e.g. `trading-bot-prod-v2`) so you can tell at a glance which key is current and which is being retired.
</Tip>

## Revoking a key

To permanently revoke an API key:

1. Go to **Settings → API Keys**.
2. Find the key you want to remove and click **Revoke**.
3. Confirm the action in the dialog. You will be asked to enter your 2FA code.

Revocation is immediate and irreversible. Any request made with the revoked key will receive a `401 Unauthorized` response. If your integration is still using that key, update it to a new one before revoking.

## Using an API key

Include 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_abc123..."
```

All API requests must be made over HTTPS. Requests over plain HTTP are rejected. Replace `bba_sk_live_abc123...` with your actual key value.

<Warning>
  Never commit an API key to a public repository, paste it into a chat, or share it with another person — including Big Brain Ape support. Treat your API key with the same level of care as a password.
</Warning>