Skip to main content
The Chirp API uses API keys to authenticate requests. Include your API key in the Authorization header as a Bearer token.

​
API Key Format

Authorization: Bearer YOUR_API_KEY
Example request: 
curl https://api.buildwithchirp.com/v1/sms \
  -H "Authorization: Bearer sk_live_app_abc123..."

​
API Key Types

Chirp provides two types of API keys for different use cases:

​
App Keys

App keys are scoped to a specific application and come in two variants: Test Keys (sk_test_app_*)
  • For development and testing
  • Work with the Playground
  • Completely free (no charges)
  • Cannot send real messages
Live Keys (sk_live_app_*)
  • For production use
  • Send real SMS/MMS messages
  • Incur charges based on usage
Permissions:
  • Send messages (POST /v1/sms)
  • Manage webhooks (/v1/webhooks)
  • Assign phone numbers (/v1/phone-numbers)
  • View message logs

​
Admin Keys

Admin keys are scoped to your organization: Format: sk_admin_* Permissions:
  • Create and manage applications
  • Manage app keys
  • Purchase and assign phone numbers
  • Manage organization settings
  • View all organization data
See Admin Keys for details.

​
Getting Your API Keys

App Keys:
  1. Log in to the Chirp dashboard
  2. Select your application
  3. Navigate to the Keys page
  4. Copy your test or live API key
Admin Keys:
  1. Log in to the Chirp dashboard
  2. Navigate to Organization Settings > Admin Keys
  3. Create a new admin key
  4. Copy the key (shown only once)

​
Security Best Practices

1. Keep Keys Secret Never expose API keys in:
  • Client-side code (JavaScript, mobile apps)
  • Public repositories
  • Version control systems
  • Public forums or documentation
2. Use Environment Variables Store API keys in environment variables: 
# .env file
CHIRP_API_KEY=sk_live_app_abc123...

const apiKey = process.env.CHIRP_API_KEY;
3. Use Test Keys for Development Always use test keys during development. Switch to live keys only when ready for production. 4. Rotate Keys Regularly For admin keys, rotate them periodically:
  1. Create a new admin key
  2. Update all services to use the new key
  3. Delete the old key
5. Use Different Keys per Environment Use separate API keys for:
  • Development
  • Staging
  • Production

​
Error Responses

Missing API Key 
{
  "error": "Missing Authorization header"
}
HTTP Status: 401 Unauthorized Invalid API Key 
{
  "error": "Invalid API key"
}
HTTP Status: 401 Unauthorized Wrong Key Type Using an app key on an admin endpoint (or vice versa): 
{
  "error": "Invalid credentials"
}
HTTP Status: 401 Unauthorized

​
Testing Authentication

Test your API key with a simple request: 
curl https://api.buildwithchirp.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_APP_KEY"
A successful response confirms your key is valid and has the correct permissions.