Authentication

Comet Engine supports two authentication methods:

Method	Headers	Use Case
API Key / Secret	X-API-Key + X-API-Secret	Per-tenant authentication (recommended)
Service Token	X-Service-Token	Internal service-to-service auth

Which Method Should I Use?

• External tenants / partners → API Key + Secret (per-tenant, scoped)
• Internal services (app-core-backend) → Service Token or API Key + Secret

Authentication Flow

Request → Comet Engine Middleware
         │
         ├── Has X-API-Key?
         │    ├── YES → Look up tenant by API key
         │    │         Validate X-API-Secret (SHA-256 + constant-time compare)
         │    │         ✅ Set tenant in context → proceed
         │    │
         │    └── NO → Check X-Service-Token
         │              Match against SERVICE_TOKENS allowlist
         │              ✅ Proceed (no tenant context)
         │
         └── Neither → 401 Unauthorized

Getting API Keys

API keys are managed through the Admin Dashboard. Contact your platform administrator to create a tenant and receive API credentials.

WARNING

The apiSecret is only returned once on creation. Store it securely.

Making Authenticated Calls

With API Key / Secret

curl http://localhost:8100/api/v1/wallets/balance?userId=1 \
  -H "X-API-Key: a1b2c3d4e5f6..." \
  -H "X-API-Secret: secret123..."

With Service Token (Legacy)

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

Tenant Scoping

When using API Key / Secret, the authenticated tenant is automatically resolved and used for all operations. You don't need to pass tenantSlug in request bodies — it's inferred from the API key.

When using Service Token, you must pass tenantSlug in request bodies or query parameters (defaults to "comet" if omitted).