Authentication

Tailstream uses token-based authentication for all API requests. There are two types of tokens depending on your use case.

Token Types

Ingest Tokens

Long-lived JWTs stored on each stream for sending log events to Tailstream.

• Purpose: Send log events via the ingest API
• Scope: Single stream
• Lifetime: Does not expire until you rotate it
• Permissions: Write access to the ingest endpoint only
• Claims: Includes stream_id (stream UUID), scope: ingest, iat, and a unique jti

Personal Access Tokens (PAT)

User-level tokens for managing streams and other management operations.

• Purpose: Stream management and data access
• Scope: User account with specific abilities
• Lifetime: Configurable
• Permissions: Based on token abilities (e.g., streams:create, streams:read)

Using Tokens

All API requests must include an Authorization header:

Authorization: Bearer <TOKEN>

Example Request

curl -X POST https://your-tailstream-instance.com/api/ingest/acme \
  -H "Content-Type: application/x-ndjson" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
  --data-binary @logs.ndjson

Token Management

Locating Ingest Tokens

• When you create a stream (via the dashboard or POST /api/streams), the response contains the stream's ingest token.
• You can fetch the token again at any time with GET /api/streams/{stream}.

Token Rotation

• Generate a new token from the dashboard (or rotate it manually via the database/API tools you use).
• Update your agents with the new token and redeploy them.
• Remove the old token from your configuration to prevent accidental use.

Error Responses

Security Best Practices

• Store tokens securely - Use environment variables or secret management systems
• Rotate regularly - Implement token rotation as part of your security workflow
• Scope appropriately - Use ingest tokens for shipping logs, PATs for management
• Monitor usage - Watch for unexpected authentication errors in your logs