Authentication

Every call to /v1 carries a bearer API key. Keys identify your tenant, resolve to a brand, and drive billing.

Header

Authorization: Bearer wsk_live_8f3a…48hex

Key lifecycle

  1. Your account manager (or — once self-serve ships — you) provisions a tenant and issues a key from POST /tenants/<id>/api-keys.
  2. The response includes the plaintext secret exactly once. Store it in your secrets manager immediately; we keep only a SHA-256 hash.
  3. Revoke compromised keys via POST /tenants/<id>/api-keys/<keyId>/revoke. Revoked keys return 401 immediately.
You cannot retrieve an existing key's secret. If you've lost a key, issue a new one and revoke the old.

Modes

Key prefixBehaviourBilling
wsk_live_Production. Real ledger writes. Drives real player engagement.Counted toward your plan's MAP + API quotas.
wsk_test_Sandbox. Same surface, isolated.Free.

Scopes

Default scope is "*" (full surface). For production deployments, request narrower scopes per integration:

ScopeWhat it allows
players:readGET /v1/players/* and timelines
players:writeUpsert players, change status, set RG
events:writeFire wager / deposit / journey events
engagement:readList engagement entities
engagement:writeOpen lootbox, enter/draw raffles, contribute/drop jackpots, play mini-games, score/close tournaments
bonuses:grantGrant a bonus template to a player

Per-tenant rate limit

Token bucket per tenant: 200 burst, 50 sustained req/sec by default. Burst over → 429 RATE_LIMIT. Enterprise plans are tunable upward.

Error responses

# Missing key
401 { "error": "Missing bearer token...", "code": "AUTH_REQUIRED" }

# Bad key, revoked key, suspended tenant
401 { "error": "Invalid or revoked API key", "code": "AUTH_INVALID" }

# Rate-limit hit
429 { "error": "rate limit exceeded", "code": "RATE_LIMIT" }