Authentication

Timberlogs supports two authentication methods: API Keys and JWT tokens.

API Keys

API keys are the recommended method for server-side applications and SDKs.

Key Format

API keys follow the format: tb_{environment}_{random}

• tb_live_* - Production keys
• tb_test_* - Test/development keys

Using API Keys

Include your API key in the Authorization header:

curl -X POST https://timberlogs-ingest.enaboapps.workers.dev/v1/logs \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"logs": [...]}'

Or use the X-API-Key header:

curl -X POST https://timberlogs-ingest.enaboapps.workers.dev/v1/logs \
  -H "X-API-Key: tb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"logs": [...]}'

Creating API Keys

1. Sign in to app.timberlogs.dev 
2. Select your organization
3. Navigate to Settings > API Keys
4. Click Create API Key
5. Store the key securely - it’s only shown once

Key Security

• Keys are hashed before storage (we never store the raw key)
• Use environment variables to store keys in your applications
• Rotate keys periodically
• Revoke compromised keys immediately

JWT Authentication

JWT tokens are used by the Timberlogs dashboard and can be used for custom integrations.

Clerk JWT

If you’re using Clerk for authentication, Timberlogs can validate Clerk-issued JWTs directly:

curl -X GET https://timberlogs-ingest.enaboapps.workers.dev/v1/logs \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

The JWT must contain:

• sub - User ID
• org_id - Organization ID (from Clerk organization context)

Organization Context

When using JWT authentication, you can specify the organization via:

1. org_id claim in the JWT (automatic with Clerk Organizations)
2. Query parameter: ?organizationId=org_xxx

# Using query parameter
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs?organizationId=org_xxx" \
  -H "Authorization: Bearer <clerk-jwt>"

Error Responses

401 Unauthorized

{
  "error": "Missing API key or JWT"
}

{
  "error": "Invalid API key"
}

{
  "error": "API key has been revoked"
}

{
  "error": "API key has expired"
}

{
  "error": "Invalid JWT token"
}

403 Forbidden

{
  "error": "Access denied to organization"
}

{
  "error": "User has no organization"
}

404 Not Found

{
  "error": "Organization not found"
}

Best Practices

1. Use API keys for server-side code - They’re simpler and don’t expire
2. Use JWTs for user-facing applications - They carry user context
3. Store keys securely - Never commit API keys to version control
4. Use different keys per environment - Separate test and production keys
5. Rotate keys regularly - Especially after team changes