API Key / Secret Authentication

Each tenant gets a unique API Key (public identifier) and API Secret (private, used to authenticate).

Getting Your API Keys

API keys are managed through the Admin Dashboard. Contact your platform administrator to:

1. Create a new tenant
2. Receive your API Key and API Secret

DANGER

The apiSecret is only shown once. Write it down immediately — it cannot be recovered.

Using the API Key/Secret

Headers

Header	Value	Required
X-API-Key	Your tenant's API key	Yes
X-API-Secret	Your tenant's API secret	Yes

Example: Get Wallet Balance

curl "http://localhost:8100/api/v1/wallets/balance?userId=123" \
  -H "X-API-Key: d4e5f6a7b8c9..." \
  -H "X-API-Secret: ef56gh78ij90kl12mn34..."

Example: Create a Wallet

curl -X POST http://localhost:8100/api/v1/wallets/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: d4e5f6a7b8c9..." \
  -H "X-API-Secret: ef56gh78ij90kl12mn34..." \
  -d '{"userId": 123}'

TIP

When using API Key/Secret, you don't need to pass tenantSlug — the tenant is automatically resolved from the API key.

How It Works

1. Engine receives X-API-Key header
2. Looks up tenant by API key in MongoDB
3. Computes SHA-256 of provided X-API-Secret
4. Compares hash with stored api_secret_hash using constant-time comparison (prevents timing attacks)
5. If valid → sets tenant in request context → proceeds
6. If invalid → returns 401 Unauthorized

Implementation Details

• API Key: 40-character random hex string (public, used for lookup)
• API Secret: 64-character random hex string (private, never stored plaintext)
• Secret Hash: SHA-256 of the secret, stored in MongoDB
• Secret Prefix: First 8 characters of the secret (for identification in logs/UIs)