Service Token Authentication (Legacy)

The original authentication method using a shared secret via X-Service-Token header.

How It Works

1. Configure SERVICE_TOKENS env var with comma-separated allowed tokens
2. Client sends X-Service-Token: <token> header
3. Engine compares against the allowlist
4. If match → proceeds. If not → 401 Unauthorized

Configuration

SERVICE_TOKENS=token1,token2,token3

Usage

curl http://localhost:8100/api/v1/wallets/balance?userId=1 \
  -H "X-Service-Token: e33421bd5f0663d04000b1c0c289d3678d2eb4f66de353166f4f1bdcbac690c2"

Scope

Service Token auth grants full access to all tenants and all operations. It does not set a tenant context — you must pass tenantSlug in request bodies or query params.

When to Use

• Internal service-to-service communication (app-core-backend → comet-engine)
• Admin endpoints (/api/v1/admin/*) require service token auth
• Legacy integrations that haven't migrated to API key/secret

Migration to API Key/Secret

For new integrations, prefer API Key/Secret auth:

• Per-tenant isolation
• Rotatable secrets
• No shared secrets across services

See API Key / Secret →