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 tokens for sending log events to Tailstream.

• Purpose: Send log events via the ingest API
• Scope: Single organization
• Lifetime: Configurable (default: 180 days)
• Permissions: Write access to ingest endpoint only

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:issue-token)

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

Creating Ingest Tokens

Use your PAT to create ingest tokens:

curl -X POST https://your-tailstream-instance.com/api/streams/{stream}/ingest-token \
  -H "Authorization: Bearer <USER_PAT>" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 15552000}'

Token Rotation

Rotate ingest tokens regularly for security:

1. Generate a new token using the API
2. Update your services with the new token
3. Restart/reload your log shipping services
4. Revoke the old token

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