Device Approval (Consoles & TVs)

When you need it

Use this anywhere the client running your title cannot invoke a platform authenticator in-process: consoles, TV apps, and native Steam / desktop game clients on both Mac and Windows. Web and mobile clients use the same hosted page, they differ from a console only in that they can open a browser, so the SDK opens the page for them (a popup on the web, the system browser on iOS / Android) instead of drawing a QR. One approval flow, one page, every platform.

Which method on which platform

The right verification method is a property of the platform the player is on. Where a passkey can run in-client it is always the strongest option, hardware-bound, phishing-resistant, and free of any messaging cost. Where the client cannot invoke a platform authenticator, use the QR device-approval flow on this page. This table is the canonical mapping; the other verification pages point back here.

The flow

Starting an approval

With the player’s SDK session token. flow is the action being approved: transfer, send, send_receipt or transfer_receipt. channel (optional, default qr) says how the client will deliver the page; it changes only how the page says “done” afterwards, you poll in every case.

POST /api/sdk/approvals/device/begin
Authorization: Bearer <sdk_session_token>
Content-Type: application/json

{
  "transaction_id": "TXN_...",
  "flow": "transfer",
  "channel": "qr"                           // qr (default) | popup | app_browser
}

200 OK
{
  "device_code": "b1s4...",                 // secret; keep it on your server
  "user_code": "K7QP-3MRD",                 // show this
  "verification_uri": "https://invo.network/device",
  "verification_uri_complete": "https://invo.network/device?user_code=K7QP-3MRD",
  "expires_in": 600,
  "interval": 5,
  "channel": "qr"                           // echoed; standard RFC 8628 clients ignore it
}

Whatever the channel, money moves only when your side calls the flow’s approve endpoint with the device_code. The page’s signal cannot approve anything.

Polling

Poll no faster than interval seconds. The error codes are the RFC 8628 ones, so a standard client understands them without translation.

POST /api/sdk/approvals/device/poll
Authorization: Bearer <sdk_session_token>

{ "device_code": "b1s4..." }

Authorization: Bearer <that player's session token>
Content-Type: application/json
{ "device_code": "b1s4..." }

flow "send"              ->  POST /api/sdk/send/{transaction_id}/approve
flow "transfer"          ->  POST /api/sdk/transfers/{transaction_id}/approve          (plural)
flow "send_receipt"      ->  POST /api/sdk/send/{transaction_id}/confirm-receipt
flow "transfer_receipt"  ->  POST /api/sdk/transfers/{transaction_id}/confirm-receipt

200 -> { "status": "approved", "next": "pending_claim", ... }        (the approves)
200 -> { "status": "completed", "amount_received": "45.00" }         (the confirm-receipts)

While a phone is waiting to enrol: the enrollment object

The first time a player scans with a phone that has no INVO passkey, the phone asks your title’s screen to vouch for it. While that is pending, the authorization_pending body carries one extra key. It is absent when no phone has asked, an already-enrolled phone never triggers it.

400 Bad Request
{
  "error": "authorization_pending",
  "enrollment": {
    "state": "awaiting_screen",               // awaiting_screen | confirmed | denied
    "device_label": "iPhone",
    "match_code": "48-27",                    // the phone page shows the same code
    "recovery": false,                        // true: the phone is REPLACING a lost INVO passkey
    "requested_at": "2026-09-03T18:04:12+00:00"
  }
}

Show a Yes/No prompt while state is awaiting_screen, “Set up INVO on iPhone? Code 48-27. Say Yes only if the phone you just scanned shows this code.”, and take it down the moment the state changes or the object disappears. The player confirms a match, not a guess by label: draw match_code large. device_label comes from a fixed list (iPhone, iPad, Android phone, Android device, Mac, Windows PC, Chromebook, Linux device, phone) derived from the scanning phone’s browser: a hint for the player, not an identity. Lead the copy with “scanned just now”, the honest signal is whether they just scanned.

When recovery is true the phone has declared it is replacing a passkey the player lost, so word the prompt as “Replace your INVO passkey with this iPhone?” rather than “set up”. The answer goes to the same confirm-enrollment call; what happens next is in Recovering a lost passkey below. On an app_browser grant the object appears already confirmed, with no awaiting_screen phase.

Confirming the phone from the title’s screen

Same authentication as begin and poll, the sender’s SDK session token, which must belong to the grant’s own identity. Send the player’s answer as soon as they give it.

POST /api/sdk/approvals/device/confirm-enrollment
Authorization: Bearer <sdk_session_token>
Content-Type: application/json

{
  "device_code": "b1s4...",
  "decision": "approve"                     // approve | deny
}

200 OK
{ "status": "confirmed" }                   // or { "status": "denied" }

Approve lets the phone continue to its biometric; your poll shows enrollment.state: "confirmed" and then status: approved. Deny ends the grant: the next poll returns access_denied, and the phone is told it was declined on the title’s screen.

Recovering a lost passkey

A player whose only INVO passkey was on a phone they no longer have can replace it from the approval page, with nothing new on your side. Recovery needs both halves of the identity: the title’s screen (this phone is theirs) and the email on file (an emailed link). Never the screen alone, so a shared console cannot reset its owner’s passkey.

1. On the page the player taps “Recover my passkey by email”. The phone asks to enrol with recovery: true; your poll shows the enrollment object with "recovery": true and a match code. Show “Replace your INVO passkey with this iPhone? Code 48-27” and send the answer to confirm-enrollment as usual. On mobile this step is auto-confirmed like any other enrolment.
2. Only after the screen has confirmed, the page emails a single-use recovery link to the address on file for the identity (never an address the page supplies; one recovery per identity per 24 hours). The player opens it on the same phone; that tab confirms and the page they started from carries on by itself.
3. Both proofs held, INVO deactivates the identity’s INVO passkeys, notifies the owner on every channel it has, enqueues an identity.passkey_reset webhook to your backend, and the phone creates its new passkey and settles the approval, your poll reports status: approved and device_approval.approved fires.

The completion webhook

Subscribe to device_approval.approved and your server hears the moment an approval lands. Polling still works on its own, the webhook is a latency improvement, not a replacement, and you should not rely on it as your only signal.

{
  "event_id": "...",
  "idempotency_key": "...",              // DEDUPE ON THIS
  "event_type": "device_approval.approved",
  "schema_version": "1.0",
  "created_at": "2026-09-04T18:04:12+00:00",
  "tenant_id": "155963559928",
  "data": {
    "transaction_id": "TXN_...",
    "flow": "transfer",                  // decides WHICH endpoint you call next
    "identity_id": "9f2c...",
    "method": "device_grant_webauthn"
  }
}

// No device code is in this payload, deliberately — a webhook body lands in your logs.
// You already hold it from the begin response. This event is the CUE to make the approve /
// confirm-receipt call, not a substitute for it.

Rules worth knowing

What this is not for

Currency purchases on a console go through that console’s own store, as required by the platform holder. This flow is for approving transfers and sends, moving currency a player already has.