Skip to main content
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": "[email protected]", "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..."

​
Login

curl -X POST https://your-tell-server/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'
Returns: 
{
  "token": "tell_eyJhbG...",
  "user": { "id": "...", "email": "[email protected]", "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.

​
CLI login

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

TypeFormatUsed for
JWT tokentell_eyJhbG...HTTP API (queries, dashboards, management)
Streaming keya1b2c3d4... (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