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.

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 — so tell us the exact domain the prompt appears on. Un-enrolled users fall back to SMS automatically. See Platform Step-Up (WebAuthn).

Key rotation

Expect a secure handoff, not a self-serve change

• The SDK secret_key rotates with no overlap — the old key is invalid immediately, so swap it promptly when you receive a new one.
• The webhook signing secret rotates 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.
• New values are handed to you over a secure channel — never in chat or committed to a repo. If a key is ever exposed, tell us and we rotate it.