> ## 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.

# App Keys

> Managing application-level API keys

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](/concepts/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:

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

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

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

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