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

# Authentication

> JWT tokens for the HTTP API, streaming keys for data ingestion.

Tell uses two auth systems: **JWT tokens** for the HTTP API (dashboards, queries, management) and **streaming API keys** for data ingestion (SDKs, TCP, syslog). Both are workspace-scoped.

## Quick start

First-time setup creates your admin account and returns both token types:

```bash theme={null}
# Check if setup is needed
curl https://your-tell-server/api/v1/auth/setup/status

# Create the first admin
curl -X POST https://your-tell-server/api/v1/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "your-password"}'
```

The setup response includes a JWT token for immediate API access and a streaming key for SDK ingestion.

## JWT tokens (HTTP API)

All API requests use a `tell_`-prefixed JWT token in the Authorization header:

```bash theme={null}
curl https://your-tell-server/api/v1/metrics/dau?range=30d \
  -H "Authorization: Bearer tell_eyJhbG..."
```

### Login

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

Returns:

```json theme={null}
{
  "token": "tell_eyJhbG...",
  "user": { "id": "...", "email": "you@example.com", "role": "editor" },
  "expires_at": 1728000000
}
```

Tokens expire after 24 hours by default.

### Refresh

Extend a token's expiry without re-entering credentials:

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"token": "tell_eyJhbG..."}'
```

Returns a new token. The old token is invalidated.

### Logout

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/auth/logout \
  -H "Authorization: Bearer tell_eyJhbG..."
```

This ends the current session and revokes the token so it can't be reused.

### CLI login

The CLI stores credentials in your OS keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service):

```bash theme={null}
tell login
tell logout
```

## Streaming API keys (data ingestion)

SDKs and pipeline sources use 32-character hex keys to authenticate data ingestion:

```
a1b2c3d4e5f60718293a4b5c6d7e8f90
```

Each key maps to a workspace. You get your first streaming key during setup. Manage additional keys with the CLI:

```bash theme={null}
tell apikeys create
tell apikeys list
tell apikeys delete <key-id>
```

See [API Keys](/running-tell/api-keys) for the full reference.

## Sessions

Tell tracks sessions per device with IP address and user agent. You can be logged in from multiple devices simultaneously. The `logout` endpoint terminates all sessions at once.

## Rate limiting

Auth endpoints are rate-limited to **10 requests per minute** per IP address. If you exceed this, you'll receive a `429 Too Many Requests` response with a `Retry-After: 60` header.

## Token format

| Type          | Format                       | Used for                                   |
| ------------- | ---------------------------- | ------------------------------------------ |
| JWT token     | `tell_eyJhbG...`             | HTTP API (queries, dashboards, management) |
| Streaming key | `a1b2c3d4...` (32 hex chars) | Data ingestion (TCP, HTTP source, syslog)  |

JWT tokens contain the user ID, email, role, and workspace ID. Streaming keys map directly to a workspace ID with no additional claims.

## What's next

* [Roles & Permissions](/running-tell/roles) — what each role can do
* [API Keys](/running-tell/api-keys) — managing streaming and programmatic keys
* [Workspaces](/running-tell/workspaces) — multi-tenant workspace isolation