Authentication Setup

LogFlux uses two types of credentials for different purposes. Understanding the distinction is important for correct configuration.

Credential Types

LogFlux has two separate authentication mechanisms, each with its own token format and purpose:

API Keys authenticate applications and agents that send log data. They are used for the /v1/ingest and /v1/handshake/* endpoints on the Ingestor service.

PATs authenticate users and tools that read log data. They are used for queries, analytics, key retrieval, and management operations on the Backend service.

Both credential types include a region prefix (eu, us, ca, au, ap) that enables automatic endpoint discovery — SDKs and agents use it to connect to the correct regional servers without manual URL configuration.

Examples

# API Key (for log ingestion via Agent/SDKs)
eu-lf_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# Personal Access Token (for log queries via CLI/Grafana)
eu-lf_usr_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Note: Legacy keys without a region prefix (lf_... or lf_usr_...) are still accepted but region-prefixed keys are recommended for all new setups.

Get Your Credentials

API Key (for Log Collection)

1. Go to https://dashboard.logflux.io
2. Navigate to Settings → API Keys
3. Click Create New API Key
4. Enter a descriptive name (e.g., “production-agent”)
5. Click Generate Key
6. Important: Copy the key immediately — it won’t be shown again
7. Use this key in your LogFlux Agent or SDK configuration

Personal Access Token (for Log Analysis)

1. Go to https://dashboard.logflux.io
2. Navigate to Settings → API Keys
3. Click Create New Personal Access Token
4. Enter a descriptive name for your token
5. Select appropriate permissions (typically “Read Logs” and “Write Logs”)
6. Click Generate Token
7. Important: Copy the token immediately — it won’t be shown again
8. Use this token with LogFlux Inspector CLI, API Server, or Grafana Plugin

Configure Authentication

Agent / SDK Configuration (API Key)

1
2

# Set your API key for log ingestion
export LOGFLUX_API_KEY="eu-lf_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Or in the agent configuration file:

1
2

# /etc/logflux-agent/agent.yaml
api_key: eu-lf_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

CLI / Grafana Configuration (PAT)

1
2
3
4
5

# Set your PAT for log queries and analysis
export LOGFLUX_PAT="eu-lf_usr_your_token_here"

# Verify the token is set
echo $LOGFLUX_PAT

1
2
3
4
5
6
7
8

# Login with your PAT (CLI clients)
logflux-inspector auth login --token eu-lf_usr_your_token_here

# Verify authentication
logflux-inspector auth status

# View current user
logflux-inspector auth whoami

Set Up Encryption Keys

LogFlux clients require your RSA private key for decrypting logs locally.

Generate Key Pair (First Time Setup)

If you don’t have RSA keys yet:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Create LogFlux directory
mkdir -p ~/.logflux

# Generate RSA key pair (4096-bit recommended)
openssl genrsa -out ~/.logflux/private_key.pem 4096

# Generate public key
openssl rsa -in ~/.logflux/private_key.pem -pubout -out ~/.logflux/public_key.pem

# Set secure permissions
chmod 600 ~/.logflux/private_key.pem

Configure Private Key

Environment Variable Method

1
2

# Set private key path
export LOGFLUX_PRIVATE_KEY_FILE="~/.logflux/private_key.pem"

Client Configuration Method

1
2
3
4
5

# For CLI clients
logflux-inspector config set-key --private-key-file ~/.logflux/private_key.pem

# Verify key configuration
logflux-inspector config get encryption.private_key_file

Grafana Plugin Configuration

1. Start the LogFlux API Server: make run-client-api-server
2. In Grafana, go to Configuration → Data Sources → Add data source
3. Select LogFlux and configure the API Server URL (http://localhost:8383)
4. Set your PAT and private key path in the API Server configuration
5. Click Save & Test to verify connectivity

Verify Setup

Test Authentication

1
2
3
4

# Test connection and authentication
logflux-inspector auth status --verbose

# Should show: "✓ Authenticated as [your-email]"

Test Decryption

1
2
3
4

# Test that you can decrypt logs
logflux-inspector logs --limit 1

# Should show decrypted log content, not encrypted data

Troubleshooting

Authentication Issues

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Check token format
# API Key: should match {region}-lf_
# PAT: should match {region}-lf_usr_
echo $LOGFLUX_PAT | grep -E "^(eu|us|ca|au|ap)-lf_usr_"

# Re-authenticate if needed
logflux-inspector auth logout
logflux-inspector auth login --token $LOGFLUX_PAT

# Check network connectivity
curl -H "Authorization: Bearer $LOGFLUX_PAT" https://api.inspect.eu.logflux.io/v1/auth/verify

# Test static discovery (if using region-prefixed token)
curl https://discover.eu.logflux.io

Key Issues

1
2
3
4
5
6
7
8

# Verify private key file exists and has correct permissions
ls -la ~/.logflux/private_key.pem

# Test key format
openssl rsa -in ~/.logflux/private_key.pem -check

# Check file permissions (should be 600)
chmod 600 ~/.logflux/private_key.pem

Network Issues

1
2
3
4
5
6

# Test with proxy if behind corporate firewall
export HTTPS_PROXY=http://proxy.company.com:8080
logflux-inspector auth status

# Test DNS resolution
nslookup api.inspect.eu.logflux.io

Security Best Practices

1. Token Storage: Use environment variables or secure credential managers
2. Key Protection: Set proper file permissions (600) on private keys
3. Regular Rotation: Rotate PATs and encryption keys periodically
4. Backup Keys: Securely backup your private keys
5. Access Control: Limit who has access to tokens and keys
6. Network Security: Use VPNs for sensitive environments

Next Steps

After completing authentication setup:

• Install and configure LogFlux Agent for log collection
• Start using LogFlux Inspector CLI or GUI for log analysis
• Explore integrations to connect your log sources