Your first verified player

1Get a sandbox key

Sign in at console.nescio.dev and create a game. You get a test API key right away (it starts with nsc_ and is shown once). Test keys run in the sandbox: only mock passports verify, so you can try the whole flow without a real document. New games have no age check; add one any time under Minimum age.

Store the key on your server, for example as an environment variable. It is a secret: never send it to a browser or game client.

export NESCIO_API_KEY="nsc_…"

2Start a sessionserver

One call per verification attempt. No request body needed: the session uses the default verification app for your key's environment. To pick one, send {"provider": "zkpassport"} or {"provider": "self"} (see Verification apps).

curl -X POST https://api.nescio.dev/v1/game/verify/sessions \
  -H "Authorization: Bearer $NESCIO_API_KEY"

// Node 18+ (built-in fetch). An Express route your page calls.
const NESCIO = "https://api.nescio.dev";
const auth = { Authorization: `Bearer ${process.env.NESCIO_API_KEY}` };
const sessions = new Map(); // sessionId → your player id (use your database)

app.post("/api/verify/start", async (req, res) => {
  const r = await fetch(`${NESCIO}/v1/game/verify/sessions`, {
    method: "POST",
    headers: auth,
  });
  if (r.status === 429) {
    // Sandbox daily quota used up. See "Sandbox & going live".
    const { retryAfterSeconds } = await r.json();
    return res.status(503).json({ error: "try_later", retryAfterSeconds });
  }
  if (!r.ok) return res.status(502).json({ error: "verification_unavailable" });

  const { sessionId, client, expiresAt } = await r.json();
  sessions.set(sessionId, req.user.id);
  // client.kind says which app scans the QR: "self" or "zkpassport".
  res.json({ sessionId, universalLink: client.universalLink, app: client.kind, expiresAt });
});

The response (201):

{
  "sessionId": "b2f1c8e0-4a6d-4c3f-9b5e-2a1d7c9f4e6b",
  "provider": "self",
  "client": {
    "kind": "self",
    "universalLink": "https://redirect.self.xyz?selfApp=%7B%22version%22%3A2%2C…%7D",
    "selfApp": { "version": 2, "…": "…" }
  },
  "status": "pending",
  "mode": "sandbox",
  "minAge": null,
  "expiresAt": "2026-09-27T21:10:00.000Z"
}

• sessionId: keep it. You poll with it in step 5 (it's the $SESSION_ID there). Remember which of your players started it.
• client.universalLink: send this to the browser and render it as a QR. It works the same for every app. selfApp is Self's own config, passed through for teams using Self's QR component; you can ignore it.
• client.kind (and provider): which app the player scans with, "self" or "zkpassport". Use it to name the app on your page. A ZKPassport client also carries url (the same link) and an opaque requestId.
• mode: "sandbox" for a test key, "live" for a live key.
• minAge: the age this session asks the player to prove, copied from your game's setting (null = no age check). See Minimum age.
• expiresAt: the session's deadline (10 minutes by default). Poll until then, plus once more (step 5).

3Show the QR codebrowser

Your page asks your backend to start a session, then draws universalLink as a QR, whichever app the session uses. Any QR library works; this uses qrcode from a CDN (or npm install qrcode).

A Self link is long (about 750 characters), so the code is dense. Draw it at least 320 px wide, multiply by devicePixelRatio so it stays sharp, and keep error correction at L on purpose: higher levels add even more modules and make it harder to scan.

<canvas id="qr"></canvas>
<a id="open-app" hidden></a>
<p id="status" role="status"></p>

<script type="module">
  import QRCode from "https://cdn.jsdelivr.net/npm/qrcode@1.5.4/+esm";

  const status = document.getElementById("status");
  const r = await fetch("/api/verify/start", { method: "POST" });
  if (!r.ok) {
    status.textContent = "Verification is unavailable. Try again in a minute.";
    throw new Error(`start failed: ${r.status}`);
  }
  const { sessionId, universalLink, app, expiresAt } = await r.json();
  const appName = app === "zkpassport" ? "ZKPassport" : "Self";

  // 320 CSS px, drawn at the screen's pixel density so the dense code stays crisp.
  const size = 320;
  const canvas = document.getElementById("qr");
  await QRCode.toCanvas(canvas, universalLink, {
    width: size * devicePixelRatio,
    margin: 2,
    errorCorrectionLevel: "L", // intentional: the link is long
  });
  canvas.style.width = canvas.style.height = `${size}px`;

  // Players already on their phone can't scan their own screen: give them a link.
  const open = document.getElementById("open-app");
  open.href = universalLink;
  open.textContent = `Open in the ${appName} app`;
  open.hidden = false;

  // Step 5 adds the polling here.
</script>

This runs on its own: the QR appears and the player can scan it. To learn the result, add the browser code from step 5 where the last comment is.

4Scan with a mock passport

With a test key, only a mock passport verifies; a real passport won't. With Self (the default app), each tester creates one once, in the Self app:

1. Install the Self app and open it.
2. Tap the settings gear (top right), then Manage ID documents, then Generate Mock Document.
3. Set an age at or above your game's minimum age, if it has one (a younger mock is how you test the under_min_age failure), then tap Generate Mock Document.
4. Scan your page's QR from the Self app and approve the request.

Self's guide, with screenshots: Using mock passports. Their steps for the app are the same for Nescio; the parts about Self Enterprise keys don't apply to you. Stuck? See Troubleshooting mock passports.

Testing with ZKPassport? Turn on Developer Mode in the ZKPassport app to load its mock IDs (ZKPassport's dev mode guide), then scan a session started with {"provider": "zkpassport"}. One difference: every ZKPassport mock ID shares one identifier, so the sandbox treats each ZKPassport mock verification as a new player. You can't reproduce duplicate: true with it; use Self's sandbox for that.

5Poll for the result

Ask for the session every 2 seconds until it leaves pending. The API key stays on your server, so the browser polls your backend and your backend asks Nescio.

Keep polling past expiresAt until the status changes: the first read after the deadline returns expired, or verified if the proof landed just in time. Finished sessions stay readable for 24 hours after expiresAt, then return 404; save the subjectId the first time you see it.

On your server

# SESSION_ID is the sessionId from step 2
curl https://api.nescio.dev/v1/game/verify/sessions/$SESSION_ID \
  -H "Authorization: Bearer $NESCIO_API_KEY"

// Same Express app as step 2 (NESCIO, auth, sessions). Proxy the poll; act once.
app.get("/api/verify/:sessionId", async (req, res) => {
  const { sessionId } = req.params;
  const playerId = sessions.get(sessionId);
  if (!playerId) return res.status(404).json({ error: "unknown_session" });

  const r = await fetch(
    `${NESCIO}/v1/game/verify/sessions/${encodeURIComponent(sessionId)}`,
    { headers: auth },
  );
  if (r.status === 404) {
    // Unknown to Nescio, or purged 24 h after expiresAt: nothing left to wait for.
    sessions.delete(sessionId);
    return res.status(404).json({ error: "unknown_session" });
  }
  if (!r.ok) return res.status(502).json({ error: "verification_unavailable" });
  const s = await r.json();

  if (s.status === "verified") {
    // subjectId: the same for this human every time, in your game only.
    // duplicate: this passport already has a player in THIS game. Link this
    // account to that player's record, or block it. It isn't fraud.
    await linkPlayer(playerId, s.subjectId, { duplicate: s.duplicate });
  }
  if (s.status !== "pending") sessions.delete(sessionId);
  res.json({ status: s.status, duplicate: s.duplicate, reason: s.reason });
});

In the browser

Paste this into the step 3 script, in place of its last comment.

// Poll your backend (never Nescio: the key stays on your server).
async function waitForResult(sessionId, expiresAt) {
  const show = (text) => { status.textContent = text; };
  // The first read after expiresAt returns "expired" (or a late "verified"),
  // so the loop ends on its own. The cap only guards against a silent backend.
  const giveUpAt = Date.parse(expiresAt) + 60_000;
  while (Date.now() < giveUpAt) {
    const r = await fetch(`/api/verify/${encodeURIComponent(sessionId)}`);
    if (r.status === 404) {
      return show("This code is no longer valid. Start again for a new one.");
    }
    if (r.ok) {
      const s = await r.json();
      if (s.status === "verified") {
        return show(s.duplicate
          ? "This passport already has an account in this game."
          : "Verified. Welcome!");
      }
      if (s.status === "failed") {
        return show(s.reason === "under_min_age"
          ? "You need to meet this game's minimum age to play."
          : "Verification failed. Start again to retry.");
      }
      if (s.status === "expired") {
        return show("The code expired. Start again for a new one.");
      }
    } // any other error is a hiccup: keep polling
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
  show("We couldn't get a result. Start again for a new code.");
}

waitForResult(sessionId, expiresAt);

The poll always returns every field; those that don't apply yet are null. A verified session:

{
  "sessionId": "b2f1c8e0-4a6d-4c3f-9b5e-2a1d7c9f4e6b",
  "status": "verified",
  "provider": "self",
  "client": { "kind": "self", "universalLink": "https://redirect.self.xyz?selfApp=…" },
  "duplicate": false,
  "reason": null,
  "mode": "sandbox",
  "expiresAt": "2026-09-27T21:10:00.000Z",
  "subjectId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

6Read the player's claimsserver

Any time later, look up what a subjectId proved. You never get the underlying document.

# SUBJECT_ID is the subjectId from a verified session
curl https://api.nescio.dev/v1/game/players/$SUBJECT_ID \
  -H "Authorization: Bearer $NESCIO_API_KEY"

const r = await fetch(
  `${NESCIO}/v1/game/players/${encodeURIComponent(subjectId)}`,
  { headers: auth },
);
if (r.status === 404) throw new Error("not a player of this game");
const { claims } = await r.json(); // an array: one record per verification method

// The highest age proven, e.g. 18; 0 if no game ever asked.
const provenAge = Math.max(0, ...claims.map((c) => c.age_proven ?? 0));
const nationality = claims[0]?.issuing_country; // e.g. "FRA", or null

{
  "subjectId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "claims": [
    {
      "method": "document_nfc",
      "assurance_level": "substantial",
      "verified_human": 1,
      "over_18": 1,
      "age_proven": 18,
      "issuing_country": "FRA",
      "verified_at": "2026-09-27T21:02:41.512Z"
    }
  ]
}

Verification apps

Players verify in one of two apps, each reading the passport's NFC chip and proving on the phone: Self ("self") and ZKPassport ("zkpassport", which adds an on-device face match). Nescio decides which apps each environment offers and which one is the default; your game's settings in the dashboard show both, for sandbox and live keys. Today sandbox keys offer both apps, with Self as the default, and live keys offer Self.

• Default: send no body and the session uses the default app for your key's environment.
• Pick one: send {"provider": "zkpassport"} (or "self"). An app that isn't on for your key's environment returns 400 provider_not_enabled, listing the accepted values in enabled; no session is created and no quota is used.
• Render it the same way: draw client.universalLink as the QR for either app, and use client.kind to name the app (ZKPassport on the App Store, on Google Play).
• Each app is its own identity. The same person verifying with Self and with ZKPassport becomes two identities, with a different subjectId for each app in your game, and the second isn't flagged as a duplicate. Offering one app per game keeps one player per person.
• Sandbox: each ZKPassport mock verification counts as a new player (see step 4). On a live key, ZKPassport mock IDs fail with mock_proof_rejected.

Minimum age

New games have no age check. To require one, open your game in the dashboard and pick a minimum age in its settings: 13, 16, 18 or 21. Only a studio admin can change it.

The dashboard saves it through the studio API (PATCH /v1/studio/games/{gameId}, signed in with your dashboard account). It isn't part of the game API: your game key can't change it, and your integration doesn't need to.

• Every new session copies the setting as minAge. The QR asks the player to prove that age, and asks for no age at all when there's none.
• A player who can't prove it gets status: "failed" with reason: "under_min_age".
• Raising the age applies to sessions created afterwards; a QR already on screen keeps the age it asked for. Players who verified earlier aren't re-checked: compare their age_proven claim with the new age, and send anyone below it through a new session, which asks for the new age.

How uniqueness works across games

• One subjectId per human, per game. The same person always gets the same subjectId in your game, and a different one in every other game. The ids are derived with a secret only Nescio holds, so two games comparing notes can't link a player.
• duplicate is per game. It's true only when this passport already has a player in this game. It tells you nothing about other games: a player verified elsewhere arrives here as duplicate: false.
• duplicate: true is a second account, not fraud. You get the existing subjectId back. Link the new account to that player's record, or block it, per your rules. To ban a person, ban the subjectId: it comes back on every account they make.

Sandbox & going live

The sandbox quota

Each test key can start 500 sessions per UTC day. Every start reports what's left in the RateLimit-Limit and RateLimit-Remaining headers; a start that fails with 502 doesn't count. Over the cap, the call returns 429 with a Retry-After header (seconds until UTC midnight) and this body:

{
  "error": "quota_exceeded",
  "limit": 500,
  "retryAfterSeconds": 34200,
  "hint": "sandbox keys are capped per day — request a live key (operator-approved) for production volume"
}

Don't retry in a loop: the quota won't reset until Retry-After has passed. Tell the tester to try again later, or go live.

Going live

1. In the dashboard, open your game and choose Request live access. You get a live key right away, but it stays inactive (calls return 401) until a Nescio operator approves it.
2. Once approved, replace the test key on your server with the live key. Nothing else in your integration changes.
3. Sessions now report mode: "live" and verify real passports only; mock documents stop working. Live keys aren't daily-capped (their RateLimit-* headers read unlimited).

Sandbox and live identities are separate: a player verified in the sandbox gets a new subjectId in live.

Errors

Errors are JSON with an error code, sometimes with a detail.

Troubleshooting mock passports

More on mock documents: Self's Using mock passports, and ZKPassport's Dev mode.

Next

Every endpoint, field, and status, with response samples for each state.