Skip to main content

Authentication

Secure your API requests with your ClearBounce API key.

API Key Authentication​

All API requests must include your API key in the X-API-Key header:

X-API-Key: cb_live_your_api_key_here

Example Request​

curl -X POST https://api.clearbounce.net/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cb_live_xxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"email": "test@example.com"}'

Getting Your API Key​

  1. Log in to your ClearBounce Dashboard
  2. Navigate to the API section
  3. Your API key is displayed there
  4. Click "Copy" to copy it to your clipboard

API Key Format​

ClearBounce API keys follow this format:

cb_live_[32 random characters]

Example: cb_live_VrpDN_m23zM21ltfzjWu1_QvRy7LmQd8

Managing API Keys​

You can create multiple API keys for different applications or environments.

Create a New Key​

curl -X POST https://api.clearbounce.net/api/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"name": "Production App"}'

List Your Keys​

curl https://api.clearbounce.net/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Delete a Key​

curl -X DELETE https://api.clearbounce.net/api/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
API Key Management

API key management endpoints require JWT authentication (login token), not API key authentication. This is for security - you manage keys through the dashboard.

Security Best Practices​

1. Keep Keys Secret​

Never expose your API key in:

  • Client-side JavaScript
  • Mobile app source code
  • Public repositories
  • Logs or error messages

2. Use Environment Variables​

# .env file
CLEARBOUNCE_API_KEY=cb_live_xxxxxxxxxxxxxxxxxxxxxxxxxx
// Node.js
const apiKey = process.env.CLEARBOUNCE_API_KEY;
# Python
import os
api_key = os.environ.get('CLEARBOUNCE_API_KEY')
// PHP
$apiKey = getenv('CLEARBOUNCE_API_KEY');

3. Rotate Keys Regularly​

If you suspect a key has been compromised:

  1. Create a new API key
  2. Update your applications
  3. Delete the old key

4. Use Separate Keys for Environments​

EnvironmentKey Name
Developmentdev_key
Stagingstaging_key
Productionproduction_key

Authentication Errors​

401 Unauthorized​

Missing or invalid API key:

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solutions:

  • Check that the X-API-Key header is present
  • Verify the API key is correct (no extra spaces)
  • Ensure the key hasn't been deleted

402 Payment Required​

Insufficient credits:

{
  "statusCode": 402,
  "code": "INSUFFICIENT_CREDITS",
  "error": "Payment Required",
  "message": "Insufficient credits"
}

Solution: Purchase more credits in your dashboard.