Authentication

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:

# 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:

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

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:

{
  "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:

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

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. The CLI stores credentials in your OS keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service):

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:

tell apikeys create
tell apikeys list
tell apikeys delete <key-id>

See 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 — what each role can do
API Keys — managing streaming and programmatic keys
Workspaces — multi-tenant workspace isolation

​Quick start

​JWT tokens (HTTP API)

​Login

​Refresh

​Logout

​CLI login

​Streaming API keys (data ingestion)

​Sessions

​Rate limiting

​Token format

​What’s next