API Authentication Guide

API Authentication Guide
Overview
API authentication is the process of verifying your identity when accessing our API. This ensures only authorized users can retrieve data or perform actions on behalf of your organization.
What You Need

• An active paid plan (Professional plan required for API access)
• Admin or Owner role in your organization
• Basic understanding of API keys and HTTP requests

Step-by-Step Setup
1. Generate Your API Key

1. Navigate to Settings > API in your dashboard
2. Click "Generate New API Key"
3. Give your key a descriptive name (e.g., "Website Integration")
4. Select the appropriate scopes:

- Read: View bots, conversations, and analytics
- Write: Create and modify bots and settings
- Admin: Full access including team management
2. Secure Your API Key
⚠️ Security Notice: Treat your API key like a password!

• Copy and store your key immediately (you won't see it again)
• Never include API keys in client-side code
• Use environment variables for server applications
• Rotate keys regularly for security

3. Making API Calls
Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.yourdomain.com/v1/bots

4. Test Your Connection
Try this simple test to verify your setup:

const response = await fetch("https://api.yourdomain.com/v1/bots", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  }
});

Common Issues & Solutions
"Invalid API Key" Error

• Double-check you copied the entire key without spaces
• Verify the key hasn't expired or been revoked
• Ensure you're using the correct authorization header format

"Insufficient Permissions" Error

• Check your API key scopes match the action you're trying to perform
• Verify your plan includes API access
• Contact support if you need scope adjustments

Rate Limiting

• API calls are limited to 1000 requests per hour
• Implement exponential backoff for retries
• Cache responses when possible to reduce calls

Security Best Practices

1. Environment Variables: Store keys in env files, never in code
2. Scope Limitation: Only grant necessary permissions
3. Regular Rotation: Change keys every 3-6 months
4. Monitor Usage: Check API logs for suspicious activity
5. Revoke Unused Keys: Remove old or unused API keys immediately

Need Help?

• Review the API scopes and rate limits in your dashboard under Settings > API
• Contact support if you need higher rate limits
• Join our Discord community for developer discussions