Skip to main content
App keys are API keys scoped to a specific application. Use them to send messages, manage webhooks, and perform app-level operations.

​
Key Types

Every application automatically gets two API keys:

​
Test Keys (sk_test_app_*)

Test keys are for development and testing:
  • Work with the Playground
  • Completely free (no charges)
  • Cannot send real SMS/MMS
  • Ideal for development and CI/CD

​
Live Keys (sk_live_app_*)

Live keys are for production use:
  • Send real SMS/MMS messages
  • Incur charges based on usage
  • Use only when ready for production

​
Permissions

App keys can perform these operations: Messaging
  • Send SMS and MMS messages
  • View message history
  • Check message status
Webhooks
  • Create and manage webhooks
  • View webhook delivery logs
  • Update webhook configuration
Phone Numbers
  • Assign phone numbers to the application
  • Remove phone numbers from the application
  • View assigned phone numbers

​
Getting Your App Keys

Via Dashboard:
  1. Log in to the Chirp dashboard
  2. Select your application
  3. Navigate to the Keys page
  4. Copy your test or live key
Via API: Use an admin key to retrieve app keys programmatically: 
curl https://api.buildwithchirp.com/v1/organization/apps/{appId}/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

​
Using App Keys

Include your app key in the Authorization header: 
curl -X POST https://api.buildwithchirp.com/v1/sms \
  -H "Authorization: Bearer sk_live_app_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": ["+15559876543"],
    "text": "Hello from Chirp!"
  }'

​
Test vs Live Mode

The key you use determines the mode: Test Mode (using sk_test_app_*)
  • Messages appear in the Playground
  • No real SMS sent
  • No charges incurred
  • Webhooks triggered to test endpoints
Live Mode (using sk_live_app_*)
  • Real SMS/MMS sent
  • Charges apply
  • Production phone numbers used
  • Webhooks triggered normally

​
Switching Between Modes

To move from testing to production:
  1. Test thoroughly with your test key
  2. Verify webhooks work correctly
  3. Replace sk_test_app_* with sk_live_app_* in your code
  4. Deploy to production
No other changes required - your code works identically in both modes.

​
Creating Additional Keys

You can create multiple app keys for different purposes: Via Dashboard:
  1. Go to your application’s Keys page
  2. Click “Create Key”
  3. Enter a name (e.g., “Production Server”, “CI/CD Pipeline”)
  4. Select type (test or live)
  5. Copy the key (shown only once)
Via API: 
curl -X POST https://api.buildwithchirp.com/v1/organization/apps/{appId}/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "isTestKey": false
  }'

​
Revoking Keys

If a key is compromised, revoke it immediately: Via Dashboard:
  1. Go to your application’s Keys page
  2. Find the compromised key
  3. Click “Delete” and confirm
Via API: 
curl -X DELETE https://api.buildwithchirp.com/v1/organization/apps/{appId}/keys/{keyId} \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"
After revoking a key, it cannot be used for any API requests.

​
Best Practices

1. Keep Keys Secret Never expose app keys in:
  • Client-side code
  • Public repositories
  • Version control
  • Screenshots or documentation
2. Use Test Keys First Always develop and test with test keys before using live keys. 3. Separate Keys per Environment Use different keys for:
  • Development
  • Staging
  • Production
4. Name Keys Descriptively Use clear names like “Production Server” or “Staging Environment” to identify keys easily. 5. Rotate Keys Regularly Create new keys and phase out old ones periodically for security.

​
Troubleshooting

401 Unauthorized Error
  • Verify you’re using the correct key format
  • Check the key hasn’t been deleted
  • Ensure you’re using an app key (not an admin key)
Wrong Mode
  • Test keys only work with the Playground
  • Live keys only send real messages
  • Verify you’re using the correct key type for your environment