Skip to main content

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.

Tell has two types of keys. Streaming keys authenticate SDKs and pipeline sources sending data over TCP, HTTP, or syslog. Programmatic API keys authenticate HTTP API calls for automation and integrations.

​
Streaming keys

Streaming keys are 32-character hex strings that map directly to a workspace: 
a1b2c3d4e5f60718293a4b5c6d7e8f90
You get your first streaming key when you run setup. SDKs and pipeline sources use this key to authenticate data ingestion.

​
Managing streaming keys

Use the CLI to create, list, and delete streaming keys: 
# List keys
tell apikeys

# Create a new key for workspace 1
tell apikeys new mobile-prod --workspace 1

# Show the full key
tell apikeys show mobile-prod

# Delete a key
tell apikeys delete mobile-prod

​
Key file format

Streaming keys are stored in a key file with one key per line: 
# Production workspace
a1b2c3d4e5f60718293a4b5c6d7e8f90:1
# Staging workspace
b2c3d4e5f6071829304a5b6c7d8e9f01:2:staging
Format: {32_hex_chars}:{workspace_id}[:{optional_name}]. Lines starting with # are comments.

​
Using streaming keys

Configure your SDK with the key: 
import { Tell } from '@tell-rs/node';

const tell = new Tell({
  apiKey: 'a1b2c3d4e5f60718293a4b5c6d7e8f90',
  endpoint: 'https://your-tell-server',
});
Pipeline sources (TCP, HTTP, syslog) validate the key on every connection.

​
Programmatic API keys

For automating HTTP API calls (querying metrics, managing boards, etc.), create programmatic API keys: 
curl -X POST https://your-tell-server/api/v1/user/apikeys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline",
    "workspace_id": "ws-1",
    "expires_at": "2026-12-31T23:59:59Z"
  }'
The response includes the full key — it’s only shown once: 
{
  "key": "tell_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "id": "key_...",
  "name": "CI Pipeline",
  "key_prefix": "tell_a1b2"
}
Use it like a regular JWT token: 
curl https://your-tell-server/api/v1/metrics/dau?range=30d \
  -H "Authorization: Bearer tell_a1b2c3d4..."

​
Key options

FieldRequiredDescription
nameYesDisplay name (1-100 characters)
descriptionNoOptional description (max 500 characters)
workspace_idNoScope to a workspace (empty = user-level key)
permissionsNoSpecific permissions (empty = inherit from your role)
expires_atNoExpiration date (max 1 year from now, never expires if omitted)

​
Managing API keys

# List your keys
curl https://your-tell-server/api/v1/user/apikeys \
  -H "Authorization: Bearer $TOKEN"

# Revoke a key
curl -X DELETE https://your-tell-server/api/v1/user/apikeys/{key-id} \
  -H "Authorization: Bearer $TOKEN"
Admins can view and revoke any key in their workspace: 
# List all keys in workspace
curl https://your-tell-server/api/v1/admin/apikeys \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws-1"

# Revoke any key in workspace
curl -X DELETE https://your-tell-server/api/v1/admin/apikeys/{key-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws-1"

​
Security

  • Streaming keys use constant-time comparison to prevent timing attacks
  • Programmatic API keys are stored as SHA-256 hashes — only the key_prefix is visible after creation
  • Programmatic API keys inherit the creator’s role — they can’t do more than you can
  • Passwords are hashed with Argon2id
  • Revoked tokens are blacklisted and cannot be reused even if the JWT hasn’t expired
  • All key creation and revocation events are audit logged