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

# Authentication

> How to authenticate with the EldrStream API

# Authentication

EldrStream uses two authentication mechanisms depending on the operation:

| Operation                  | Mechanism                                         |
| -------------------------- | ------------------------------------------------- |
| Sending events (ingestion) | API Key (EldrStream-API-Key`: eldr_sk_...`)       |
| Management operations      | JWT session token (`Authorization: Bearer <jwt>`) |

***

## Login

Obtain a JWT session token by authenticating with your tenant credentials.

```text theme={null}
POST /v1/tenants/auth/login
```

### Request body

| Field      | Type   | Required | Description                                  |
| ---------- | ------ | -------- | -------------------------------------------- |
| `loginId`  | string | Yes      | Your `tenant_id` or registered email address |
| `password` | string | Yes      | Your account password                        |

### Example

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/tenants/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "loginId": "a3f8bc1d2e",
    "password": "Secur3P@ss!"
  }'
```

### Response

```json theme={null}
{
  "status": "authenticated",
  "token": "eyJhbGciOiJSUzI1NiJ9...",
  "tenant_id": "a3f8bc1d2e",
  "tenant_name": "Acme Corp",
  "tier": "pro"
}
```

| Field         | Description                              |
| ------------- | ---------------------------------------- |
| `token`       | JWT bearer token. Valid for **2 hours**. |
| `tenant_id`   | Your unique tenant identifier            |
| `tenant_name` | Your account display name                |
| `tier`        | Your current plan tier                   |

### Error responses

| Status             | Meaning                                   |
| ------------------ | ----------------------------------------- |
| `401 Unauthorized` | `loginId` not found or password incorrect |

***

## Using the JWT

Pass the token as a `Bearer` value in the `Authorization` header on all management API calls:

```text theme={null}
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
```

Tokens expire after **2 hours**. Requests made with an expired token return `401 Unauthorized`. Re-authenticate by calling `/v1/tenants/auth/login` again.

***

## Using the API Key

The API key authenticates event ingestion. Pass it as a `key` value in the `EldrStream-API-Key` header:

```text theme={null}
EldrStream-API-Key: eldr_sk_9f4c2a...
```

See [Ingestion](./ingestion.md) for the full ingest endpoint reference, and [API Keys](./api-keys.md) for how to retrieve and rotate your key.