Skip to main content
Admin keys are organization-level API keys with permissions to manage applications, phone numbers, and organization settings.

​
What are Admin Keys?

Admin keys (sk_admin_*) provide full access to your organization’s resources. Use them to:
  • Create and manage applications
  • Manage app keys
  • Purchase and assign phone numbers
  • Manage organization settings
  • View all organization data
  • Manage team members and billing

​
Permissions

Admin keys can perform all organization-level operations: Application Management
  • Create new applications
  • Update application settings
  • Delete applications
  • List all applications
App Key Management
  • Create app keys (test and live)
  • List app keys for any application
  • Revoke app keys
  • View app key details
Phone Number Management
  • Purchase phone numbers
  • Assign numbers to applications
  • Remove numbers from applications
  • View all organization phone numbers
Organization Settings
  • Update organization profile
  • Manage billing information
  • Configure organization-level webhooks
  • View usage and analytics

​
Creating Admin Keys

Via Dashboard:
  1. Log in to the Chirp dashboard
  2. Navigate to Organization Settings
  3. Click on “Admin Keys”
  4. Click “Create Admin Key”
  5. Enter a descriptive name
  6. Copy the key (shown only once)
Admin keys are shown only once during creation. Store them securely immediately.
Key Naming Best Practices:
  • “Production Automation”
  • “CI/CD Pipeline”
  • “Infrastructure Scripts”
  • “Development Tools”

​
Using Admin Keys

Include your admin key in the Authorization header: 
curl https://api.buildwithchirp.com/v1/organization/apps \
  -H "Authorization: Bearer sk_admin_abc123..."

​
Example: Create an Application

curl -X POST https://api.buildwithchirp.com/v1/organization/apps \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New App",
    "slug": "my-new-app"
  }'

​
Example: List All Applications

curl https://api.buildwithchirp.com/v1/organization/apps \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

​
Example: Create App Keys

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
  }'

​
Security Best Practices

1. Limit Admin Keys Only create admin keys when necessary. Use app keys for application-specific operations. 2. Use Descriptive Names Name keys based on their purpose:
  • ✅ “Production Automation Script”
  • ✅ “CI/CD Pipeline - GitHub Actions”
  • ❌ “Key 1”
3. Rotate Regularly For long-running services, rotate admin keys every 90 days:
  1. Create a new admin key
  2. Update all services to use the new key
  3. Verify everything works
  4. Delete the old key
4. Never Expose in Code Store admin keys in:
  • Environment variables
  • Secrets management systems (AWS Secrets Manager, HashiCorp Vault)
  • CI/CD secret stores
Never commit to version control or expose in client-side code. 5. Audit Regularly Review admin keys periodically:
  • Delete unused keys
  • Verify key names are still accurate
  • Check key activity in audit logs

​
Revoking Admin Keys

If an admin key is compromised or no longer needed: Via Dashboard:
  1. Go to Organization Settings > Admin Keys
  2. Find the key to revoke
  3. Click “Delete” and confirm
Revoking an admin key immediately invalidates it. Any services using this key will stop working.
Before revoking:
  1. Identify all services using the key
  2. Create and deploy a replacement key
  3. Verify services work with new key
  4. Revoke the old key

​
Admin Keys vs App Keys

FeatureAdmin KeysApp Keys
Formatsk_admin_*sk_live_app_* / sk_test_app_*
ScopeOrganization-wideSingle application
Create apps✅ Yes❌ No
Send messages❌ No✅ Yes
Manage phone numbers✅ YesLimited
Manage webhooks✅ YesApp-level only
Manage billing✅ Yes❌ No

​
Use Cases

Automation Scripts Use admin keys to automate organization management:
  • Create applications for new projects
  • Provision phone numbers automatically
  • Generate app keys for new environments
Infrastructure as Code Manage Chirp resources with Terraform or similar tools:
  • Define applications declaratively
  • Provision resources programmatically
  • Keep infrastructure in sync
CI/CD Pipelines Integrate Chirp into deployment workflows:
  • Create test applications automatically
  • Generate test keys for each branch
  • Clean up resources after tests
Multi-Tenant Platforms Build platforms that manage Chirp for multiple customers:
  • Create applications per customer
  • Isolate customer data
  • Manage resources programmatically

​
Troubleshooting

401 Unauthorized
  • Verify the admin key format (sk_admin_*)
  • Check the key hasn’t been deleted
  • Ensure you’re using an admin key (not an app key)
403 Forbidden
  • Verify the operation requires admin-level access
  • Check you’re not trying to send messages (use app keys)
Key Not Working After Creation
  • Admin keys are active immediately
  • Verify you copied the entire key
  • Check for extra spaces or newlines