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

# Authentication

> Learn how to authenticate your API requests

## Bearer Token Authentication

All Bouncy.ai API requests require authentication using an API key passed as a Bearer token in the `Authorization` header of every request.

## Getting Your API Key

<Steps>
  <Step title="Upgrade to Growth Plan">
    API access requires a [Growth plan](https://bouncy.ai/pricing) or higher (\$35/month).
  </Step>

  <Step title="Generate an API Key">
    1. Go to [bouncy.ai/api/dashboard](https://bouncy.ai/api/dashboard)
    2. Click **"Create New Key"**
    3. Give your key a descriptive name
    4. Copy and save your key securely
  </Step>

  <Step title="Store Securely">
    <Warning>
      Never commit API keys to version control or share them publicly. Use environment variables or a secrets manager.
    </Warning>
  </Step>
</Steps>

## API Key Format

Bouncy.ai API keys follow this format:

```
bcy_live_pk_1234567890abcdefghijklmnopqrstuvwxyz
└─┬─┘ └─┬┘ └┬┘ └───────────────┬─────────────────┘
  │     │   │                   │
  │     │   │                   └─ Random 40-character string
  │     │   └───────────────────── Key type (pk = private key)
  │     └───────────────────────── Environment (live = production)
  └─────────────────────────────── Prefix (Bouncy)
```

* **bcy\_** - Bouncy.ai identifier
* **live\_** - Production environment
* **pk\_** - Private key (keep secret!)
* **40 characters** - Random alphanumeric string

## Making Authenticated Requests

Include your API key as a Bearer token in the `Authorization` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.bouncy.ai/v1/links \
    -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch) theme={null}
  const response = await fetch('https://api.bouncy.ai/v1/links', {
    headers: {
      'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY'
    }
  });
  ```

  ```javascript JavaScript (Axios) theme={null}
  const axios = require('axios');

  const response = await axios.get('https://api.bouncy.ai/v1/links', {
    headers: {
      'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY'
    }
  });
  ```

  ```python Python (Requests) theme={null}
  import requests

  response = requests.get(
      'https://api.bouncy.ai/v1/links',
      headers={'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY'}
  )
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.bouncy.ai/v1/links');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer bcy_live_pk_YOUR_API_KEY'
  ]);
  $response = curl_exec($ch);
  ?>
  ```
</CodeGroup>

## Using Environment Variables

**Recommended**: Store your API key in an environment variable:

<CodeGroup>
  ```bash .env theme={null}
  BOUNCY_API_KEY=bcy_live_pk_YOUR_API_KEY
  ```

  ```javascript JavaScript theme={null}
  // Load from environment variable
  const apiKey = process.env.BOUNCY_API_KEY;

  const response = await fetch('https://api.bouncy.ai/v1/links', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  ```

  ```python Python theme={null}
  import os

  # Load from environment variable
  api_key = os.getenv('BOUNCY_API_KEY')

  response = requests.get(
      'https://api.bouncy.ai/v1/links',
      headers={'Authorization': f'Bearer {api_key}'}
  )
  ```
</CodeGroup>

## Managing API Keys

### Viewing Your Keys

View all your API keys in the [API Dashboard](https://bouncy.ai/api/dashboard). You can see:

* Key name and prefix (e.g., `bcy_live_pk_••••`)
* Creation date
* Last used date
* Current usage statistics

### Revoking Keys

If an API key is compromised:

1. Go to [bouncy.ai/api/dashboard](https://bouncy.ai/api/dashboard)
2. Find the compromised key
3. Click **"Revoke"**
4. Create a new key immediately
5. Update your applications with the new key

<Warning>
  Revoked keys stop working immediately and cannot be restored. All requests using a revoked key will return a `401 Unauthorized` error.
</Warning>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never commit keys to version control">
    Use `.gitignore` to exclude files containing API keys:

    ```
    .env
    .env.local
    secrets.json
    ```
  </Accordion>

  <Accordion title="Use environment variables">
    Store API keys in environment variables, not in your code:

    ```javascript theme={null}
    // Bad
    const apiKey = 'bcy_live_pk_1234567890abcdef';

    // Good
    const apiKey = process.env.BOUNCY_API_KEY;
    ```
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Create new API keys every 90 days and revoke old ones. This limits exposure if a key is compromised.
  </Accordion>

  <Accordion title="Use separate keys per environment">
    Create different API keys for development, staging, and production. This makes it easier to revoke a specific environment's access.
  </Accordion>

  <Accordion title="Restrict by IP (Scaling/Dominance plans)">
    If you have a Scaling or Dominance plan, you can whitelist specific IP addresses for your API keys.
  </Accordion>
</AccordionGroup>

## Authentication Errors

### 401 Unauthorized - Missing API Key

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer YOUR_API_KEY"
}
```

**Solution**: Include your API key as a Bearer token in the `Authorization` header.

### 401 Unauthorized - Invalid API Key

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

**Solutions**:

* Check that you've copied the full API key
* Verify the key hasn't been revoked
* Generate a new API key if needed

### 403 Forbidden - Plan Upgrade Required

```json theme={null}
{
  "error": {
    "code": "plan_upgrade_required",
    "message": "Your subscription plan does not include API access. Please upgrade to Growth or higher.",
    "currentPlan": "solo"
  }
}
```

**Solution**: [Upgrade to a Growth plan](https://bouncy.ai/pricing) or higher (\$35/month).

## Rate Limits

Rate limits are enforced per API key:

| Plan      | Requests/Hour | Requests/Day |
| --------- | ------------- | ------------ |
| Growth    | 1,000         | 10,000       |
| Scaling   | 5,000         | 50,000       |
| Dominance | 10,000        | 100,000      |

Every API response includes rate limit headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1738886400
```

See the [Error Handling Guide](/guides/error-handling) for more details on rate limiting.