Skip to main content

​
Overview

Our API uses bearer token authentication. You’ll need to include your API key in the Authorization header of every request.

​
Getting your API key

  1. Log into your dashboard
  2. Navigate to your workspace settings
  3. Click on “API Keys” section
  4. Click “Generate new API key”
  5. Copy and securely store your key
API keys are shown only once. If you lose your key, you’ll need to generate a new one.

​
Using your API key

Include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Example request

curl https://api.yourdomain.com/api/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Security best practices

​
1. Keep keys secret

Never expose API keys in:
  • Client-side code
  • Public repositories
  • Log files
  • Error messages

​
2. Use environment variables

Store API keys in environment variables: 
// Good ✅
const apiKey = process.env.MESSAGING_API_KEY;

// Bad ❌
const apiKey = 'sk_live_abcd1234...';

​
3. Rotate keys regularly

Periodically rotate your API keys:
  1. Generate a new key
  2. Update your application
  3. Revoke the old key

​
4. Use separate keys per environment

Create different keys for:
  • Development
  • Staging
  • Production

​
5. Monitor key usage

Regularly review your API key usage in the dashboard to detect any unusual activity.

​
Revoking API keys

If a key is compromised:
  1. Go to your workspace settings
  2. Find the compromised key
  3. Click “Revoke”
  4. Generate a new key immediately
Revoked keys stop working immediately. Update your applications before revoking keys in production.

​
API key permissions

API keys inherit the permissions of the workspace they’re created in. Each key can:
  • Send messages
  • Retrieve message history
  • Access workspace settings
  • Manage phone numbers

​
Troubleshooting

​
401 Unauthorized

This error means your API key is invalid or missing: 
{
  "error": "unauthorized",
  "detail": "Invalid or missing API key"
}
Solutions:
  • Check that the key is included in the header
  • Verify the key hasn’t been revoked
  • Ensure you’re using the correct key format: Bearer YOUR_KEY

​
403 Forbidden

This error means your key doesn’t have permission for this action: 
{
  "error": "forbidden",
  "detail": "Insufficient permissions for this resource"
}
Solutions:
  • Verify you’re accessing the correct workspace
  • Check that your workspace has the required features enabled

​
Session authentication

Some endpoints (primarily UI endpoints) use session authentication instead of API keys. These are typically used by our web dashboard and require user login.

​
Next steps