Partner Credentials & Key Handling

Everything your integration needs comes down to three credentials and two rules. This page is the canonical reference for what each key is, where it lives, and how to handle it safely.

Your tenant gets three things

Credential	Lives	What it's for
game_id	Anywhere	Your tenant id. Not secret.
SDK secret_key ivsdk_…	Server-side ONLY	Sent as the `X-Game-Secret-Key` header to mint player tokens and for server-to-server calls.
Webhook signing secret	Server-side ONLY	Used to verify the webhooks we send you. It is NOT sent in requests to us.

Where to find them

• game_id and the SDK secret_key — on the dashboard's Platform & Keys page (user menu, top-right → Platform & Keys → pick your game). The key has a reveal/copy affordance and a self-serve rotate.
• Webhook signing secret — shown once when you create the webhook on the dashboard's Webhooks page (and again on each rotation). Store it then; it isn't retrievable later.

Never put a secret in a frontend bundle

Anything in a browser build (Vite/React, etc.) is world-readable. The ivsdk_… secret and the webhook signing secret are server-side credentials — they must never ship to the client.

Two rules that matter

1. The browser never holds the SDK key

Your server mints a short-lived player token; the browser uses that for every /api/sdk/* call.

POST /api/sdk/player-token
  Header: X-Game-Secret-Key: <SDK secret_key>      // server-to-server ONLY
  Body:   { "player_email": "user@example.com" }   // player must exist in your tenant

→ { "token": "<player token>",                      // Authorization: Bearer <token>
    "expires_at": "...Z",                            // ~15-min lifetime, NO refresh
    "identity_id": "id_…" }
// On a 401 from any /api/sdk/* call → mint a fresh token and retry.

2. Verify every webhook

X-Invo-Signature: t=<ts>,v1=<hmac> is HMAC-SHA256 over the literal string "<timestamp>.<raw_body>", keyed with your signing secret. Verify constant-time, reject if the timestamp is outside a 5-minute window, and de-duplicate on X-Invo-Idempotency-Key.

Full reference + verify snippet: Receiving Webhooks.

Web platforms: passkey step-up

WebAuthn runs on your origin

Web platforms enroll a passkey on login and approve high-value transfers/sends with an assertion. The ceremony runs in the browser on your web origin, which must match the relying-party ID configured for your tenant. You configure the domain yourself on the dashboard's Platform & Keys page — submit the RP ID and origins, prove domain ownership with a DNS TXT record, and step-up turns on when verification passes. Un-enrolled users fall back to SMS automatically. See Platform Step-Up (WebAuthn).

Key rotation

Both keys rotate self-serve, both with a 7-day grace window

• The SDK secret_key rotates from the dashboard's Platform & Keys page (user menu → Platform & Keys → your game → Rotate key). The old key keeps working for 7 days so your integration can cut over without downtime — the new key is shown once in a copy dialog, and the page banners the grace deadline.
• The webhook signing secret rotates from the dashboard's Webhooks page, also with a 7-day grace window — deliveries are dual-signed (two v1= values) so you can deploy the new value without downtime. X-Invo-Secret-Version tells you which is current.
• If a key is ever exposed, rotate it immediately from the console — don't wait on us. Never share keys in chat or commit them to a repo.