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

# Introduction

> CaseBender API endpoints

<Card title="CaseBender Endpoints" icon="leaf" href="https://demo.casebender.com/api/openapi.json">
  View the OpenAPI specification file
</Card>

## Authentication

All API endpoints require authentication using API keys. Include your API key in every request using one of the following methods:

### Recommended: Bearer Token

Include your API key as a Bearer token in the `Authorization` header:

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

### Alternative: X-Api-Key Header

You can also use the `X-Api-Key` header:

```bash theme={null}
X-Api-Key: cbr_live_your_api_key_here
```

<Warning>
  **Important**: Your API key grants access to your CaseBender instance. Keep it secure and never share it publicly.
</Warning>

### Creating API Keys

To create API keys:

1. Log in to your CaseBender instance
2. Navigate to **Account** → **API Keys**
3. Click **Create API Key**
4. Configure the key name, description, tier, and scopes
5. **Save the key immediately** - it is displayed only once and cannot be retrieved later

When you create an API key, you'll receive a single key that looks like:

```
cbr_live_a1b2c3d4e5f6g7h8i9j0...
```

### Using API Keys

Include the API key in all API requests:

#### Using cURL

```bash theme={null}
curl -X GET https://your-instance.casebender.com/api/v1/alerts \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"
```

#### Using Python (requests library)

```python theme={null}
import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY_HERE",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://your-instance.casebender.com/api/v1/alerts",
    headers=headers
)
```

#### Using JavaScript/Node.js (fetch)

```javascript theme={null}
const response = await fetch(
  "https://your-instance.casebender.com/api/v1/alerts",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY_HERE",
      "Content-Type": "application/json",
    },
  }
);
```

### API Key Tiers

API keys record an intended service tier. Effective limits are enforced by the
deployment and can be lower than the tier's nominal ceiling. No tier bypasses
tenant, scope, TLP, owner-status, or organization policy.

| Tier         | Requests/Minute    | Requests/Hour      | Burst Allowance    |
| ------------ | ------------------ | ------------------ | ------------------ |
| Basic        | 60                 | 1,000              | 10                 |
| Standard     | 300                | 10,000             | 50                 |
| Professional | 1,000              | 50,000             | 100                |
| Enterprise   | 5,000              | 200,000            | 500                |
| Unlimited    | Deployment-defined | Deployment-defined | Deployment-defined |

### API Key Scopes

When creating an API key, you can limit its access to specific operations:

* `alerts:read` - Read alerts
* `alerts:write` - Create and update alerts
* `cases:read` - Read cases
* `cases:write` - Create and update cases
* `observables:read` - Read observables
* `observables:write` - Create and update observables
* `users:read` - Read user information
* Administrative scopes are shown only when the key manager already possesses
  the corresponding permission

The API rejects attempts to create a key with scopes or TLP clearance broader
than the caller. Each key remains bound to its server-derived owner and
organization.

### Common Authentication Errors

* **401 Unauthorized**:
  * Missing `Authorization` header
  * Invalid or expired API key
  * API key has been revoked or suspended
  * API key owner has been disabled, locked, or deleted

* **403 Forbidden**:
  * API key lacks required scope for the operation
  * Organization, team, parent-object, or TLP access restrictions

* **429 Too Many Requests**:
  * Rate limit exceeded for your tier

### Security Best Practices

* **Never share your API key** - treat it like a password
* **Rotate API keys regularly** - revoke old keys and create new ones periodically
* **Use different keys for different applications** - this allows you to revoke access per application
* **Set expiration dates** - configure API keys to expire automatically when possible
* **Use minimum required scopes** - only grant the permissions your application needs

Only `Authorization: Bearer` and `X-Api-Key` are supported. Query-string
credentials and split legacy key/secret headers are not accepted.