Platform Step-Up (WebAuthn / Passkeys)

How it works

There are two ceremonies, mirroring the mobile flow:

• • Enrollment (once per browser/device): create a passkey and register its public key.
• • Approval (per high-value action): sign a challenge bound to the specific transfer or send.

Games that verified their own passkey domain before October 2026 keep working until they remove it. New domains can’t be added, and there is nothing to configure.

If your players enrol on your domain, you must implement linkDevice()

This is the one thing a tenant with its own verified passkey domain has to build, and the one thing that strands players if it is missing. It applies to every title whose players hold a passkey minted on the partner’s origin, and the symptom is always the same: the player scans the QR, or the popup opens, and INVO’s hosted approval page refuses to go any further.

HTTP/1.1 409 Conflict
{
  "code":  "ENROLLMENT_REQUIRES_PROOF",
  "next":  "link",
  "error": "You already approve with a passkey on the game's own website. ..."
}

Branch on the server’s verdict, never on a guess

Read the error code and next from the body and dispatch on those. Do not try to infer the right path from which credentials your front end can see: a browser cannot enumerate a player’s passkeys, still less the methods that live on another device, so any guess you make there will be wrong for somebody.

import { InvoError } from '@invonetwork/web-sdk';

async function enrolWithFallback(invo, onLostCredential) {
  try {
    await invo.enrollPasskey();
  } catch (e) {
    if (!(e instanceof InvoError)) throw e;

    // ENROLLMENT_REQUIRES_PROOF / next: "link"
    // They still HAVE a method: prove it here, on your origin, then retry.
    if (e.isEnrollmentProofRequired) {
      await invo.linkDevice();        // no arguments: the server mints the link id
      await invo.enrollPasskey();     // retry; the single-use grant is consumed for you
      return;
    }

    // PASSKEY_ALREADY_ENROLLED, or the player says the credential is gone.
    // ONLY here. Recovery deactivates the existing passkey and starts a
    // temporary hold on money out (the 403 carries retry_after).
    if (e.code === 'PASSKEY_ALREADY_ENROLLED') {
      await onLostCredential();       // recoveryBegin + recoveryComplete, then enrol
      return;
    }

    throw e;
  }
}

Make it friendly on the front end

The player should never see a status code. What they should see is one obvious action, and a clearly secondary escape hatch that spells out its cost before they commit to it.

The same rule and the same refusal are described from the hosted page’s side on Device Approval.

1. Enroll a passkey

POST /api/sdk/player-token
  Header: X-Game-Secret-Key: <your game secret>     // server-to-server ONLY
  Body:   { "player_email": "user@example.com" }

→ { "token": "<player token>",                       // use as Authorization: Bearer
    "expires_at": "2026-01-01T12:15:00Z",            // ~15-minute lifetime, no refresh
    "identity_id": "id_9f3c…" }
// 404 player_not_found · 403 sdk_not_enabled_for_tenant · on 401 mint a fresh token

// options came from /register/begin. Convert base64url fields to ArrayBuffers
// (challenge, user.id) before calling create(), then base64url-encode the
// result's ArrayBuffers (rawId, attestationObject, clientDataJSON) to send back.
const options = await (await fetch('/api/sdk/webauthn/register/begin', {
  method: 'POST', headers: { Authorization: 'Bearer ' + playerToken }
})).json();

const cred = await navigator.credentials.create({ publicKey: toBuffers(options) });

await fetch('/api/sdk/webauthn/register/complete', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + playerToken, 'Content-Type': 'application/json' },
  body: JSON.stringify({ credential: toJSON(cred) })   // base64url-encoded
});

2. First enrolment when your tenant requires authorisation

By default a player’s first passkey enrols freely. The player token your server minted is the proof. A tenant can opt in to a stronger gate: the first enrolment must also prove the player controls the email or phone the identity was built from. With that switch on, a first /webauthn/register/complete (or mobile /device/register) with no grant on file returns 409 ENROLLMENT_REQUIRES_AUTHORIZATION. It is off unless you turn it on, so an integration that has not added these two calls is unaffected.

try {
  await client.enrollPasskey();
} catch (e) {
  if (e instanceof InvoError && e.isEnrollmentAuthorizationRequired) {
    await client.enrollmentBegin();               // code → email on file
    await client.enrollmentVerify(codeFromUser);  // 6-digit code
    await client.enrollPasskey();                 // retry; grant auto-consumed
  } else throw e;
}

3. Lost or replaced passkey (recovery)

Deleting a passkey on the device never tells the server the key is gone, so the next enrolment is blocked by the anti-takeover gate with 409 ENROLLMENT_REQUIRES_PROOF, and the player has nothing left to prove with. Recovery is the possession-proofed way out: offer a “Lost or replaced your passkey?” action that runs these two calls, then the normal enrolment ceremony again.

// web SDK
if (e instanceof InvoError && e.isEnrollmentProofRequired) {
  await client.recoveryBegin();                 // code → email on file
  await client.recoveryComplete(codeFromUser);  // → { status: "recovered", deactivatedCount }
  await client.enrollPasskey();                 // same call, now succeeds
}

Still have the other method, and only want to add this one? That is linking, not recovery. See the note under section 1.

4. Approve an action with the passkey

Use a passkey assertion in place of the mobile device_signal. First get a challenge bound to the specific transaction, then submit the assertion to the same approval endpoint you'd use otherwise.

const options = await (await fetch(`/api/sdk/transfers/${id}/approve/webauthn/begin`, {
  method: 'POST', headers: { Authorization: 'Bearer ' + playerToken }
})).json();

const assertion = await navigator.credentials.get({ publicKey: toBuffers(options) });

const res = await fetch(`/api/sdk/transfers/${id}/approve`, {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + playerToken, 'Content-Type': 'application/json' },
  body: JSON.stringify({ webauthn_assertion: toJSON(assertion) })
});
// 200 { status: "approved", next: "pending_claim", claim_code: "…" }

Why it's strong