From 94f57b589151ca434a5a457f338f6f639c7b3e0c Mon Sep 17 00:00:00 2001 From: Noam Date: Fri, 17 Jul 2026 15:43:31 -0700 Subject: [PATCH 1/7] docs(world-id): add Sandbox environment guide Introduce a new Sandbox section covering the dedicated, production-like testing environment: what it is and how to install the sandbox World ID app and point an integration at it. Co-Authored-By: Claude Sonnet 5 --- docs.json | 7 +++ world-id/sandbox/sandbox-access.mdx | 70 ++++++++++++++++++++++++++++ world-id/sandbox/what-is-sandbox.mdx | 54 +++++++++++++++++++++ 3 files changed, 131 insertions(+) create mode 100644 world-id/sandbox/sandbox-access.mdx create mode 100644 world-id/sandbox/what-is-sandbox.mdx diff --git a/docs.json b/docs.json index 1472397..430ebf3 100644 --- a/docs.json +++ b/docs.json @@ -83,6 +83,13 @@ } ] }, + { + "group": "Sandbox", + "pages": [ + "world-id/sandbox/what-is-sandbox", + "world-id/sandbox/sandbox-access" + ] + }, { "group": "Credentials", "pages": [ diff --git a/world-id/sandbox/sandbox-access.mdx b/world-id/sandbox/sandbox-access.mdx new file mode 100644 index 0000000..88e7c51 --- /dev/null +++ b/world-id/sandbox/sandbox-access.mdx @@ -0,0 +1,70 @@ +--- +title: "How to get access" +description: "Install the sandbox World ID app and point your integration at the Sandbox environment." +"og:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png" +"twitter:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png" +--- + +{/* cspell:ignore idkit TestFlight VZEurhHe Eurh */} + +Getting set up in Sandbox has two parts: install the **sandbox World ID app** on your +test device, and point your **integration** at the Sandbox environment. Both are +covered below. + +New here? Start with [What is Sandbox?](/world-id/sandbox/what-is-sandbox) for context. + +## 1. Install the sandbox World ID app + +The sandbox builds are not published to the App Store or Google Play. You install them +directly using the links below. + +### iOS — TestFlight + +1. Install [TestFlight](https://apps.apple.com/app/testflight/id899247664) from the + App Store if you don't have it. +2. Open the public TestFlight link to join the external tester group: + [testflight.apple.com/join/VZEurhHe](https://testflight.apple.com/join/VZEurhHe) +3. Install the **World ID (Sandbox)** build from TestFlight. + +No App Store Connect account or per-email invite is required — the public link admits +you to the external tester group directly. + +### Android + +The sandbox build is available on **both** the Google Play testing track and Firebase +App Distribution — use whichever you prefer. + +1. Open the invite/download link we provide for your chosen channel. +2. Follow the link to install the **World ID (Sandbox)** build. + +If you install via Firebase App Distribution, you may be prompted to install the App +Tester helper the first time. + + +Contact your World point of contact to get the current Android links. + + +## 2. Point your integration at Sandbox + +1. **Update IDKit** to a version with Sandbox support. +2. **Select Sandbox** as the destination for your verification requests, instead of + Production. +3. Run a request from your surface — the handoff will open the sandbox World ID app and + return a proof to your session over the bridge. + +## Things to know + +- **Sandbox apps aren't in the app stores.** Because the builds are distributed + directly to testers, install/store deep links won't route to a store listing the way + they do in production. Testers install via TestFlight (iOS) or the Android link + instead — so any journey that depends on a real store install can't be exercised + exactly as it will be in production. +- **Proofs are non-production.** Identities and proofs issued in Sandbox are for + integration validation only. +- **Accounts are resettable.** You can delete and recreate accounts freely while + testing. + +## Next step + +Once you're installed and pointed at Sandbox, you're ready to run the Selfie Check +integration flows. (Testing those flows is covered in a separate guide.) diff --git a/world-id/sandbox/what-is-sandbox.mdx b/world-id/sandbox/what-is-sandbox.mdx new file mode 100644 index 0000000..40f4ef8 --- /dev/null +++ b/world-id/sandbox/what-is-sandbox.mdx @@ -0,0 +1,54 @@ +--- +title: "What is Sandbox?" +description: "An isolated, production-like environment for testing your World ID integration end-to-end." +"og:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png" +"twitter:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png" +--- + +{/* cspell:ignore idkit TestFlight */} + +Sandbox is a dedicated, production-like environment for building and testing your +World ID integration. It runs alongside Production as its own environment, with its +own backend and its own builds of the World ID app for iOS and Android. + +It lets you run a complete integration — from your app or website, through IDKit, into +the World ID app, and back — without touching production identities or issuing real +proofs. + +## Why use Sandbox + +Sandbox is built for integration testing. It gives you: + +- **A full end-to-end round trip.** Sandbox is a valid IDKit destination, so you can + drive a real request from your surface into the World ID app and receive a proof + back over the bridge — the same path your production integration will use. +- **Resettable accounts.** Delete an account and sign up again as often as you need. +- **Simulated verification.** Exercise verification flows without real hardware or + real-world credentials. +- **Controllable gating.** You decide whether the system enforces fraud, risk, and + attestation checks. Turn enforcement off to move quickly through integration testing, + or turn it on to validate how your integration behaves under production-like gating. + +## What you can test + +The full relying-party journey from your surface into the World ID app and back: +request handoff, consent, capture, enrollment and matching, proof generation, and +delivery of the proof to your session. + +Both same-device (deep link) and cross-device (QR) flows are supported, on both iOS +and Android sandbox builds. + +## What Sandbox is not + +- **Not production.** Accounts and proofs issued in Sandbox are for integration + validation only — not load testing, security certification, or production sign-off. +- **Not a source of real uniqueness.** Sandbox does not represent real-world identity + or uniqueness at scale. +- **Not published to the app stores.** The sandbox World ID builds are distributed + directly to testers rather than through the App Store or Google Play. See + [How to get access](/world-id/sandbox/sandbox-access) for how to install them. + +## Next step + +Ready to try it? Head to [How to get access](/world-id/sandbox/sandbox-access) to +install the sandbox app and point your integration at Sandbox. From 47263016d729660e839627b6f99ca6ef8d3b3713 Mon Sep 17 00:00:00 2001 From: Noam Date: Fri, 17 Jul 2026 16:06:05 -0700 Subject: [PATCH 2/7] docs(world-id): link Selfie Check testing guide from Sandbox access Co-Authored-By: Claude Sonnet 5 --- world-id/sandbox/sandbox-access.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/world-id/sandbox/sandbox-access.mdx b/world-id/sandbox/sandbox-access.mdx index 88e7c51..a8af500 100644 --- a/world-id/sandbox/sandbox-access.mdx +++ b/world-id/sandbox/sandbox-access.mdx @@ -67,4 +67,5 @@ Contact your World point of contact to get the current Android links. ## Next step Once you're installed and pointed at Sandbox, you're ready to run the Selfie Check -integration flows. (Testing those flows is covered in a separate guide.) +integration flows. See [Testing Selfie Check in Sandbox](/world-id/sandbox/testing-selfie-check) +for coverage, critical user journeys, and known limitations. From f540609c41847c179113700faa575e0031347136 Mon Sep 17 00:00:00 2001 From: Noam Date: Fri, 17 Jul 2026 16:10:49 -0700 Subject: [PATCH 3/7] docs(world-id): Android sandbox distribution is Firebase App Distribution only Per the Android team, Google Play testing track is not being used for Sandbox distribution right now. Co-Authored-By: Claude Sonnet 5 --- world-id/sandbox/sandbox-access.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/world-id/sandbox/sandbox-access.mdx b/world-id/sandbox/sandbox-access.mdx index a8af500..0931d2a 100644 --- a/world-id/sandbox/sandbox-access.mdx +++ b/world-id/sandbox/sandbox-access.mdx @@ -31,14 +31,12 @@ you to the external tester group directly. ### Android -The sandbox build is available on **both** the Google Play testing track and Firebase -App Distribution — use whichever you prefer. +The sandbox build is distributed via **Firebase App Distribution**. -1. Open the invite/download link we provide for your chosen channel. +1. Open the invite/download link we provide. 2. Follow the link to install the **World ID (Sandbox)** build. -If you install via Firebase App Distribution, you may be prompted to install the App -Tester helper the first time. +You may be prompted to install the App Tester helper the first time. Contact your World point of contact to get the current Android links. From c86318e56f92ee72d998d8a99516d244fdf45630 Mon Sep 17 00:00:00 2001 From: Noam Date: Mon, 20 Jul 2026 10:38:37 -0700 Subject: [PATCH 4/7] docs(world-id): simplify Sandbox integration steps per review Address review feedback: replace the vague "update IDKit / select Sandbox" steps with the concrete config change (environment: sandbox) and drop the extra step describing IDKit's normal runtime behavior. Co-Authored-By: Claude Sonnet 5 --- world-id/sandbox/sandbox-access.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/world-id/sandbox/sandbox-access.mdx b/world-id/sandbox/sandbox-access.mdx index 0931d2a..d51ad76 100644 --- a/world-id/sandbox/sandbox-access.mdx +++ b/world-id/sandbox/sandbox-access.mdx @@ -44,11 +44,11 @@ Contact your World point of contact to get the current Android links. ## 2. Point your integration at Sandbox -1. **Update IDKit** to a version with Sandbox support. -2. **Select Sandbox** as the destination for your verification requests, instead of - Production. -3. Run a request from your surface — the handoff will open the sandbox World ID app and - return a proof to your session over the bridge. +1. **Update IDKit** to the latest version. +2. **Set `environment: sandbox`** in your IDKit configuration. + +Nothing else is required — the handoff will open the sandbox World ID app and return a +proof to your session over the bridge. ## Things to know From 499dd361364697848f92b086941c2bd2d09f095e Mon Sep 17 00:00:00 2001 From: Noam Date: Fri, 17 Jul 2026 16:07:44 -0700 Subject: [PATCH 5/7] docs(world-id): add Selfie Check Sandbox testing guide Add a testing guide covering coverage (entry surface x user state), critical user journeys, and known limitations for testing Selfie Check end-to-end in Sandbox. Cross-link it from the Selfie Check credential page and the IDKit credentials integration guide. Co-Authored-By: Claude Sonnet 5 --- docs.json | 3 +- world-id/credentials/11.mdx | 3 + world-id/idkit/credentials.mdx | 2 +- world-id/sandbox/testing-selfie-check.mdx | 68 +++++++++++++++++++++++ 4 files changed, 74 insertions(+), 2 deletions(-) create mode 100644 world-id/sandbox/testing-selfie-check.mdx diff --git a/docs.json b/docs.json index 430ebf3..a4aa0cd 100644 --- a/docs.json +++ b/docs.json @@ -87,7 +87,8 @@ "group": "Sandbox", "pages": [ "world-id/sandbox/what-is-sandbox", - "world-id/sandbox/sandbox-access" + "world-id/sandbox/sandbox-access", + "world-id/sandbox/testing-selfie-check" ] }, { diff --git a/world-id/credentials/11.mdx b/world-id/credentials/11.mdx index 44f0a86..1d6b58f 100644 --- a/world-id/credentials/11.mdx +++ b/world-id/credentials/11.mdx @@ -56,3 +56,6 @@ You will need to use IDKit to integrate Selfie Check (Beta) into your applicatio ## Next steps See [Web Integration Guide](/world-id/credentials#legacy-presets). + +Testing your integration? See [Testing Selfie Check in Sandbox](/world-id/sandbox/testing-selfie-check) +for coverage, critical user journeys, and known limitations. diff --git a/world-id/idkit/credentials.mdx b/world-id/idkit/credentials.mdx index bca3249..8b33c43 100644 --- a/world-id/idkit/credentials.mdx +++ b/world-id/idkit/credentials.mdx @@ -107,7 +107,7 @@ const preset = passport({ signal: "user-123" }); Selfie Check is available through the legacy preset today and returns a World ID 3.0 Face proof. World ID 4.0 support is rolling out soon. -Learn more in [Selfie Check](/world-id/credentials/11). +Learn more in [Selfie Check](/world-id/credentials/11). To test your integration end-to-end, see [Testing Selfie Check in Sandbox](/world-id/sandbox/testing-selfie-check). ```typescript title="JavaScript" diff --git a/world-id/sandbox/testing-selfie-check.mdx b/world-id/sandbox/testing-selfie-check.mdx new file mode 100644 index 0000000..8979460 --- /dev/null +++ b/world-id/sandbox/testing-selfie-check.mdx @@ -0,0 +1,68 @@ +--- +title: "Testing Selfie Check in Sandbox" +description: "Coverage, critical user journeys, and known limitations for testing your Selfie Check integration in Sandbox." +"og:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png" +"twitter:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png" +--- + +{/* cspell:ignore idkit DoB reinstalls */} + +Sandbox lets you run the full [Selfie Check](/world-id/credentials/11) relying-party +journey end-to-end — from your surface, through IDKit, into the sandbox World ID app, +and back — without touching production identities or real proofs. + +New to Sandbox? Start with [What is Sandbox?](/world-id/sandbox/what-is-sandbox) and +[How to get access](/world-id/sandbox/sandbox-access) before working through this +guide. + + + In scope: the full relying-party journey — request handoff, consent, capture, + enrollment and matching, proof generation, and delivery of the proof. Out of scope: + production identity data and real-world uniqueness at scale. Sandbox accounts and + proofs are for integration testing only, not load testing, security certification, + or production sign-off. + + +## Coverage + +Testing is organized by entry surface and user state, using the same [Hot, Cold, and +Semi-cold states](/world-id/idkit/verification-flows) as the rest of World ID: + +- **Hot** — the user already has World ID installed. If they're already Selfie Check + enrolled, they go straight to face match; if not, World ID walks them through + enrollment first, then match. (Selfie Check has no distinct Warm flow — enrollment + happens inline within Hot, same as [Verification Flows](/world-id/idkit/verification-flows) + describes.) +- **Cold** — a new user with no World ID app: the full funnel, including install, + account creation, date of birth, invite code (iOS), enrollment, and Selfie Check. +- **Semi-cold** — an existing user without World ID on this device: reinstall and + account recovery, then Selfie Check. + +| Entry surface | State | What it exercises | +| --- | --- | --- | +| Native app | Hot | Same-device: validated user presents a face credential; deep link into World ID and back. | +| Native app | Cold | Install → create account → add date of birth → redeem invite code → enroll → complete Selfie Check. | +| Native app | Semi-cold | Existing user reinstalls and recovers their account on a fresh device, then completes Selfie Check. | +| Web app | Hot | Cross-device: start on web, complete on phone via QR scan, proof returns to the web session. | +| Web app | Cold | Same cold funnel, cross-device via QR; proof returns to the originating web session. | +| Web app | Semi-cold | Same semi-cold recovery, cross-device via QR. | + +## Known limitations + +- **Sandbox apps aren't published to the app stores.** As with other Sandbox testing, + install deep links won't route to a store listing the way they do in production — + see [How to get access](/world-id/sandbox/sandbox-access#things-to-know). This means + the Cold and Semi-cold journeys above can't be exercised exactly as they will be once + the app is on the App Store or Play Store. +- **iOS Semi-cold is currently limited.** The reinstall/login journey reliably works on + Android today. On iOS, if the user taps "Sign in" instead of "Sign up" mid-flow, + there's no path to add the invite code — they have to restart from a fresh QR or deep + link. Expect iOS Semi-cold to behave differently from Android until this is closed. +- **Invite-code handling in the Cold flow differs by platform.** Confirm how invite + codes are presented and redeemed on the platform you're targeting — see + [invite-code mode](/world-id/idkit/verification-flows#with-invite-code-mode). + +## Next step + +Questions, or found a journey these scenarios don't cover? Reach out to your World +point of contact. From 40dd882ef2d32da67b53d2b4d1ccd7f40978c3c0 Mon Sep 17 00:00:00 2001 From: Noam Date: Fri, 17 Jul 2026 16:23:52 -0700 Subject: [PATCH 6/7] chore: trigger preview build From bb869c543944eeb435dd085483a7de4c2ab953db Mon Sep 17 00:00:00 2001 From: Noam Date: Tue, 21 Jul 2026 13:07:28 -0700 Subject: [PATCH 7/7] docs(world-id): note Sandbox builds share Production's release process Co-Authored-By: Claude Sonnet 5 --- world-id/sandbox/what-is-sandbox.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/world-id/sandbox/what-is-sandbox.mdx b/world-id/sandbox/what-is-sandbox.mdx index 40f4ef8..e00540f 100644 --- a/world-id/sandbox/what-is-sandbox.mdx +++ b/world-id/sandbox/what-is-sandbox.mdx @@ -9,7 +9,9 @@ description: "An isolated, production-like environment for testing your World ID Sandbox is a dedicated, production-like environment for building and testing your World ID integration. It runs alongside Production as its own environment, with its -own backend and its own builds of the World ID app for iOS and Android. +own backend and its own builds of the World ID app for iOS and Android, built from +the same codebase and release process as Production — so Sandbox is just as stable +and reliable. It lets you run a complete integration — from your app or website, through IDKit, into the World ID app, and back — without touching production identities or issuing real