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

# Admin Keys

> Managing organization-level API keys

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)

<Warning>Admin keys are shown only once during creation. Store them securely immediately.</Warning>

**Key Naming Best Practices:**

* "Production Automation"
* "CI/CD Pipeline"
* "Infrastructure Scripts"
* "Development Tools"

## Using Admin Keys

Include your admin key in the `Authorization` header:

```bash theme={null}
curl https://api.buildwithchirp.com/v1/organization/apps \
  -H "Authorization: Bearer sk_admin_abc123..."
```

### Example: Create an Application

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

```bash theme={null}
curl https://api.buildwithchirp.com/v1/organization/apps \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"
```

### Example: Create App Keys

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

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

<Warning>
  Revoking an admin key immediately invalidates it. Any services using this key will stop working.
</Warning>

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

| Feature              | Admin Keys        | App Keys                          |
| -------------------- | ----------------- | --------------------------------- |
| Format               | `sk_admin_*`      | `sk_live_app_*` / `sk_test_app_*` |
| Scope                | Organization-wide | Single application                |
| Create apps          | ✅ Yes             | ❌ No                              |
| Send messages        | ❌ No              | ✅ Yes                             |
| Manage phone numbers | ✅ Yes             | Limited                           |
| Manage webhooks      | ✅ Yes             | App-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