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

# Authentication

> How to authenticate requests to the Caspr API

All Caspr API requests require an API key passed as a Bearer token in the `Authorization` header.

## Get an API key

API keys are scoped per organization and provisioned by our team. Email [support@usepeppr.ai](mailto:support@usepeppr.ai) with your organization name to request access.

Keys look like:

```
pk_live_a1b2c3d4e5f6...
```

> [!WARNING]
>
> **Treat your API key like a password.** Never commit keys to source control, paste them into shared docs, or expose them in client-side code. If a key leaks, contact support immediately to rotate it.

## Making authenticated requests

Include the key in the `Authorization` header on every request.

```bash cURL theme={null}
curl https://caspr-copilot-prod.usepeppr.ai/api/copilot-sessions \
  -H "Authorization: Bearer pk_live_..."
```

```python Python theme={null}
import httpx

client = httpx.Client(
    base_url="https://caspr-copilot-prod.usepeppr.ai/api",
    headers={"Authorization": "Bearer pk_live_..."},
)
```

```javascript JavaScript theme={null}
const caspr = (path, init = {}) =>
  fetch(`https://caspr-copilot-prod.usepeppr.ai/api${path}`, {
    ...init,
    headers: {
      Authorization: "Bearer pk_live_...",
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
```

## Scoping

Every API key is bound to a single organization. All responses are automatically filtered to resources that belong to that organization — you cannot read another customer's data even if you knew their session IDs.

Within an organization, the key has read and write access to:

* Sessions, transcripts, and threads
* Call analysis and notes
* Knowledge base (connectors, QA pairs, documents)
* Dashboard analytics

## Rate limits

> [!NOTE]
>
> Rate limits are enforced per API key.

| Tier | Requests per minute | Burst |
| - | - | - |
| Standard | 60 | 120 |
| Enterprise | 300 | 600 |

When you exceed the limit, Caspr returns `429 Too Many Requests` with a `Retry-After` header indicating how many seconds to wait before retrying.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{ "detail": "Rate limit exceeded" }
```

For higher limits, reach out to [support@usepeppr.ai](mailto:support@usepeppr.ai).

## Error responses

All errors follow the same envelope.

```json theme={null}
{ "detail": "Not authenticated" }
```

> [accordion] 401 Unauthorized
>
> The API key is missing, malformed, or revoked. Check that your `Authorization` header is present and uses the format `Bearer pk_live_...`.

> [accordion] 403 Forbidden
>
> Your API key is valid but doesn't have access to the requested resource. This typically means the resource belongs to a different organization.

> [accordion] 404 Not Found
>
> The resource doesn't exist, or your key doesn't have access to it. Caspr returns `404` (not `403`) for resources you can't access, to avoid leaking existence information.

> [accordion] 429 Too Many Requests
>
> You've hit the rate limit. Back off using the `Retry-After` header value.

> [accordion] 5xx Server errors
>
> Something went wrong on our side. `5xx` responses are safe to retry with exponential backoff — idempotent reads (`GET`) won't double-process.

## Security best practices

> [!TIP]
>
> **Store keys in environment variables or secret managers** — never in code.

> [!TIP]
>
> **Use different keys per environment** — separate dev, staging, and production.

> [!TIP]
>
> **Rotate keys periodically** — especially after employee changes.

> [!TIP]
>
> **Scope responsibly** — use the lowest-privilege key that gets the job done.

> [!TIP]
>
> **Monitor usage** — unexpected traffic spikes may indicate a compromised key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.