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.

Current user

Check who a token belongs to:

curl https://your-tell-server/api/v1/auth/me \
  -H "Authorization: Bearer tell_eyJhbG..."

Returns:

{ "id": "...", "email": "you@example.com", "role": "editor" }

Any authenticated user can call it, and it is not rate-limited like the other auth endpoints. A missing, invalid, or revoked token returns 401. 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.

List responses

Every endpoint that returns a list of one kind of resource uses the same shape:

{
  "items": [ ... ],
  "total": 134,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

items holds one page of results.
total counts every matching row across all pages, not just this page.
limit and offset echo the page you got.
has_more is true when rows exist past this page.

Page with the limit and offset query parameters:

Parameter	Default	Description
`limit`	`50`	Page size. Values above `200` are clamped to `200`.
`offset`	`0`	Rows to skip.

Boards, canvases, board groups, and workspace lists (/boards, /canvases, /board-groups, /user/workspaces, /admin/workspaces) default to limit=200 so a plain request returns everything for typical workspaces. The maximum is still 200. Some lists add fields beside these five. For example, /people also returns all_time and total_events_scope. Single resources and analytics results (metric series, funnels, retention) don’t use this shape.

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

​Current user

​CLI login

​Streaming API keys (data ingestion)

​Sessions

​Rate limiting

​List responses

​Token format

​What’s next