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

# Authorization

> Who can access Esper and which workspace they're allowed to operate — covering operator authentication, memberships, and bearer tokens.

## API Key Authentication

<Info>
  **API Key Validation**

  All ingest endpoints require valid API keys for authentication:

  * **Header**: API keys must be passed in the `x-esper-api-key` header
  * **Response**: Invalid or missing keys return `401 Unauthorized`
  * **Scope**: API keys are tenant-scoped
</Info>

API keys are the primary mechanism for authenticating ingest traffic. Each key is bound to a specific tenant, ensuring proper isolation and attribution of ingested events.

<Tip>
  **Cloud Uses API Keys Only**

  For `cloud`, customers do not need operator bearer tokens. They send
  traffic directly to Esper with `x-esper-api-key`.
</Tip>

### Rate Limiting

API keys are rate limited. Exceeding the limit returns `429 Too Many Requests`.
Limits are applied independently per API key so one source's traffic does not
affect another.

## Operator authentication

The current dashboard model is bearer-token based.

Hosted browser flow:

1. The operator starts from an auth route such as `/auth/github/login`.
2. The backend issues a JWT after successful callback.
3. The frontend stores the token as `esper.auth_token`.
4. API requests send `Authorization: Bearer <token>`.

Important backend behavior:

* The server now has dedicated auth middleware.
* Dashboard routes require a bearer JWT before tenant membership checks run.
* Invalid tokens return `401`.

## Membership management

Memberships are tenant-scoped. The UI supports:

* Create or update a membership with `user_id` and `role`.
* Remove a membership by `user_id`.

Endpoints:

```text theme={null}
GET /api/v1/tenants/{tenant_id}/memberships
POST /api/v1/tenants/{tenant_id}/memberships
DELETE /api/v1/tenants/{tenant_id}/memberships/{user_id}
```

Supported roles:

| Role      | Current meaning            |
| --------- | -------------------------- |
| `Owner`   | highest tenant role        |
| `Admin`   | administrative operator    |
| `Analyst` | analysis-oriented operator |
| `Viewer`  | read-oriented operator     |