Skip to main content

API keys

Every integrating application (for example a sportsbook or a partner platform) is registered by Winam as a separate API client and receives its own API key. All API requests must include the header:
The full key is shown only once, when Winam issues it. Store it in your secret manager. If you lose it, ask Winam for a new key — it cannot be recovered. Contact support@eins-innovativ.de to register an application or obtain a key.
Never expose your API key in client-side code (browser, mobile app). Always call the API from your backend.

Scopes

Each application is granted a set of scopes. A valid key without the scope required by a route receives 403. Reference routes only need a valid key, no scope: GET /api/v1/{country}/providers, GET /api/v1/{country}/providers/status, POST /api/v1/msisdn/detect, GET /api/v1/security/callback-public-key. By default an application has all three scopes.

401 vs 403

Isolation between applications

  • Transactions are private to the application that created them. Reading, listing or replaying the webhook of a transaction created by another application returns 404, exactly as if it did not exist. GET /api/v1/players/{player_id}/transactions only lists your own transactions.
  • reference is unique across the whole platform. Re-sending a reference you already used returns your original transaction (idempotency, 200). Sending a reference already used by another application returns 409 {"detail": "Reference already used by another application."} — use references that are unique to you (for example prefixed with your platform name).
  • Default callback URL. When a deposit or withdrawal request has no callback_url, the webhook is sent to the default_callback_url configured for your application (if any).
  • Webhooks are signed with your application’s own secret. See Webhook verification.

Key rotation without downtime

An application can hold several active keys at once. To rotate:
  1. Ask Winam for a new key — the existing key keeps working.
  2. Deploy the new key on your side.
  3. Ask Winam to revoke the old key. From then on it returns 401.

Unauthenticated endpoints

The only endpoint that does not require authentication is:
  • GET /health — infrastructure health check (used by load balancers)

Webhook verification

Outbound webhooks (sent from winam-payments to your callback_url) carry an HMAC-SHA256 signature computed with your application’s webhook secret in the X-Winam-Signature header (t=<unix>,v1=<hex>). See Webhooks for verification details.