Skip to main content

​
API Key Authentication

All Bouncy.ai API requests require authentication using an API key. Include your API key in the X-Api-Key header of every request.

​
Getting Your API Key

1

Upgrade to Growth Plan

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

Generate an API Key

  1. Go to bouncy.ai/api/dashboard
  2. Click “Create New Key”
  3. Give your key a descriptive name
  4. Copy and save your key securely
3

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 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 in the X-Api-Key header: 
curl https://api.bouncy.ai/v1/links \
  -H "X-Api-Key: bcy_live_pk_YOUR_API_KEY"

​
Using Environment Variables

Recommended: Store your API key in an environment variable: 
BOUNCY_API_KEY=bcy_live_pk_YOUR_API_KEY

​
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_••••)
  • Creation date
  • Last used date
  • Current usage statistics

​
Revoking Keys

If an API key is compromised:
  1. Go to 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
Revoked keys stop working immediately and cannot be restored. All requests using a revoked key will return a 401 Unauthorized error.

​
Security Best Practices

Use .gitignore to exclude files containing API keys:
.env
.env.local
secrets.json
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;
Create new API keys every 90 days and revoke old ones. This limits exposure if a key is compromised.
Create different API keys for development, staging, and production. This makes it easier to revoke a specific environment’s access.
If you have a Scaling or Dominance plan, you can whitelist specific IP addresses for your API keys.

​
Authentication Errors

​
401 Unauthorized - Missing API Key

{
  "error": {
    "code": "missing_api_key",
    "message": "API key is required. Include it in X-Api-Key header."
  }
}
Solution: Include your API key in the X-Api-Key header.

​
401 Unauthorized - Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid or has been revoked"
  }
}
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:
PlanRequests/HourRequests/Day
Growth1,00010,000
Scaling5,00050,000
Dominance10,000100,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 for more details on rate limiting.