Authentication

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

Upgrade to Growth Plan

API access requires a Growth plan or higher ($35/month).

Generate an API Key

Go to bouncy.ai/api/dashboard
Click “Create Key”
Give your key a descriptive name
Choose a role: Full Access, Creator, or Viewer (read only)
Copy and save your key securely

Store Securely

Never commit API keys to version control or share them publicly. Use environment variables or a secrets manager.

API Key Format

Bouncy.ai API keys follow this format:

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

bcy_ - Bouncy.ai identifier
live_ - Production environment
pk_ - Private key (keep secret!)
64 characters - Random hex string

Making Authenticated Requests

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

curl https://api.bouncy.ai/v1/links \
  -H "Authorization: Bearer bcy_live_pk_YOUR_API_KEY"

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

const axios = require('axios');

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

import requests

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

<?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);
?>

Using Environment Variables

Recommended: Store your API key in an environment variable:

BOUNCY_API_KEY=bcy_live_pk_YOUR_API_KEY

// 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}`
  }
});

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}'}
)

API Key Roles

Every key gets a role when you create it. The role controls which endpoints the key can call. You can have up to 10 active keys, so you can hand out narrowly scoped keys instead of sharing your main one.

Role	Can	Cannot
Full Access	Read and write everything: links, analytics, domains, websites, groups, account
Creator	Create and edit links, groups and websites; read analytics and domains	Modify domains; read your account profile
Viewer	Read links, analytics, domains, websites, groups and usage stats	Any create, update or delete; read your account profile

Give third parties a Viewer key. They can pull analytics and read data, but they cannot create or change anything on your account.

The rule of thumb: GET endpoints need read permission for their resource, and everything else needs write permission. GET /v1/account/profile is the exception: it returns account owner details (email, name, billing), so only Full Access keys can call it. Keys created before roles existed keep working unchanged, with full access.

Insufficient permissions error

When a key calls an endpoint outside its role, the API returns 403 Forbidden:

{
  "error": "Forbidden",
  "message": "This API key has the 'viewer' role and is not allowed to perform this action.",
  "requiredScope": "links:write",
  "keyRole": "viewer",
  "documentation": "https://docs.bouncy.ai/authentication"
}

Solution: Use a key whose role includes the required permission, or create a new key with the right role.

Managing API Keys

Viewing Your Keys

View all your API keys in the API Dashboard. You can see:

Key name and prefix (e.g., bcy_live_pk_••••)
Role (Full Access, Creator, or Viewer)
Creation date
Last used date
Current usage statistics

Revoking Keys

If an API key is compromised:

Go to bouncy.ai/api/dashboard
Find the compromised key
Click “Revoke”
Create a new key immediately
Update your applications with the new key

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

Security Best Practices

Never commit keys to version control

Use .gitignore to exclude files containing API keys:

.env
.env.local
secrets.json

Use environment variables

Store API keys in environment variables, not in your code:

// Bad
const apiKey = 'bcy_live_pk_1234567890abcdef';

// Good
const apiKey = process.env.BOUNCY_API_KEY;

Rotate keys regularly

Create new API keys every 90 days and revoke old ones. This limits exposure if a key is compromised.

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.

Use role-scoped keys

Create a Viewer key for read-only integrations and reporting tools. If that key ever leaks, it cannot be used to create or change anything on your account.

Authentication Errors

401 Unauthorized - Missing API Key

{
  "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

{
  "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

{
  "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 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
Agency	50,000	500,000

When you exceed a limit, the API returns 429 Too Many Requests with a message explaining which limit you hit and when it resets. See the Error Handling Guide for more details on rate limiting.

Get Started

Guides

Bearer Token Authentication

Getting Your API Key

API Key Format

Making Authenticated Requests

Using Environment Variables

API Key Roles

Insufficient permissions error

Managing API Keys

Viewing Your Keys

Revoking Keys

Security Best Practices

Authentication Errors

401 Unauthorized - Missing API Key

401 Unauthorized - Invalid API Key

403 Forbidden - Plan Upgrade Required

Rate Limits

​Bearer Token Authentication

​Getting Your API Key

​API Key Format

​Making Authenticated Requests

​Using Environment Variables

​API Key Roles

​Insufficient permissions error

​Managing API Keys

​Viewing Your Keys

​Revoking Keys

​Security Best Practices

​Authentication Errors

​401 Unauthorized - Missing API Key

​401 Unauthorized - Invalid API Key

​403 Forbidden - Plan Upgrade Required

​Rate Limits

Bearer Token Authentication

Getting Your API Key

API Key Format

Making Authenticated Requests

Using Environment Variables

API Key Roles

Insufficient permissions error

Managing API Keys

Viewing Your Keys

Revoking Keys

Security Best Practices

Authentication Errors

401 Unauthorized - Missing API Key

401 Unauthorized - Invalid API Key

403 Forbidden - Plan Upgrade Required

Rate Limits