Documentation menu

Authentication

Learn how to authenticate your API requests to PostBeagle.

API Keys

PostBeagle uses API keys for authentication. All API requests must include your API key in the request headers.

Generating an API Key

  1. Log in to your PostBeagle account
  2. Navigate to Settings → API
  3. Click Generate API Key
  4. Copy and securely store your API key

Using Your API Key

Include your API key in the Authorization header of every API request:

curl -X GET https://api.postbeagle.com/api/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Authentication Flow

All API requests follow this authentication pattern:

  1. Generate an API key from the dashboard
  2. Include the key in the Authorization header
  3. Make your API request
  4. Handle the response

Example Request

const response = await fetch('https://api.postbeagle.com/api/contacts', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${YOUR_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Security Best Practices

Keep Your Keys Safe

  • Never commit API keys to version control
  • Use environment variables to store keys
  • Rotate keys regularly
  • Revoke compromised keys immediately

Environment Variables

Store your API key as an environment variable:

# .env file
POSTBEAGLE_API_KEY=your_api_key_here

Then use it in your code:

const apiKey = process.env.POSTBEAGLE_API_KEY;

const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

Rate Limiting

PostBeagle API implements rate limiting to ensure fair usage:

  • Rate Limit: 100 requests per minute per API key
  • Burst Limit: 10 requests per second

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Error Responses

401 Unauthorized

Your API key is missing or invalid:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Solution: Check that your API key is correct and included in the Authorization header.

403 Forbidden

Your API key doesn't have permission to access this resource:

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Solution: Verify that your API key has the necessary permissions.

429 Too Many Requests

You've exceeded the rate limit:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds."
}

Solution: Implement exponential backoff or reduce your request frequency.

Revoking API Keys

If you suspect your API key has been compromised:

  1. Go to Settings → API
  2. Click Revoke API Key
  3. Confirm the revocation
  4. Generate a new API key

Testing Authentication

Test your authentication setup with a simple request:

curl -X GET https://api.postbeagle.com/api/account \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

A successful response confirms your authentication is working:

{
  "id": "usr_123456",
  "email": "[email protected]",
  "created_at": "2025-01-01T00:00:00Z"
}

Next Steps