> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate API requests with API keys

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

## API Key Format

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Example request:

```bash theme={null}
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](/administration_apis/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:

```bash theme={null}
# .env file
CHIRP_API_KEY=sk_live_app_abc123...
```

```javascript theme={null}
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**

```json theme={null}
{
  "error": "Missing Authorization header"
}
```

HTTP Status: `401 Unauthorized`

**Invalid API Key**

```json theme={null}
{
  "error": "Invalid API key"
}
```

HTTP Status: `401 Unauthorized`

**Wrong Key Type**

Using an app key on an admin endpoint (or vice versa):

```json theme={null}
{
  "error": "Invalid credentials"
}
```

HTTP Status: `401 Unauthorized`

## Testing Authentication

Test your API key with a simple request:

```bash theme={null}
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.