From 16aedb9b6095326f8a11417f7ba8a1d3b90e4534 Mon Sep 17 00:00:00 2001 From: Takis Kakalis <80459599+Takaros999@users.noreply.github.com> Date: Tue, 4 Aug 2026 15:06:05 -0700 Subject: [PATCH 1/3] docs: clarify world id migration guidance --- docs.json | 1 + world-id/4-0-migration.mdx | 48 +++++++++++++++--------------- world-id/credentials/11.mdx | 13 ++++---- world-id/deprecations.mdx | 18 +++++++++++ world-id/idkit/build-with-llms.mdx | 3 ++ 5 files changed, 54 insertions(+), 29 deletions(-) create mode 100644 world-id/deprecations.mdx diff --git a/docs.json b/docs.json index a4aa0cd..64faf99 100644 --- a/docs.json +++ b/docs.json @@ -103,6 +103,7 @@ "group": "Migration", "pages": [ "world-id/4-0-migration", + "world-id/deprecations", "world-id/from-idkit-standalone" ] }, diff --git a/world-id/4-0-migration.mdx b/world-id/4-0-migration.mdx index 16422e2..13cea3f 100644 --- a/world-id/4-0-migration.mdx +++ b/world-id/4-0-migration.mdx @@ -1,7 +1,6 @@ --- title: "World ID 4.0" description: "Migration guide for moving your app to World ID 4.0" -tag: "Coming Soon" "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" --- @@ -9,6 +8,10 @@ tag: "Coming Soon" ## Start Here +World ID 4.0 is available for new and existing integrations. New apps should +start with IDKit 4.x; existing apps should choose the migration path that +matches how they use World ID. + - Register or upgrade your app in the [Developer Portal](https://developer.worldcoin.org). - Upgrade to IDKit 4.x (see below). - Choose a migration path below based on your app's behavior. @@ -40,20 +43,15 @@ Adopting World ID 4.0 requires upgrading to IDKit 4.x, which introduces major br For details and example code, see the [IDKit 4.0 integration guide](/world-id/idkit/integrate). -## Migration Timeline (Phase Dates) - -Use these dates as the default migration timeline: +### Legacy credential compatibility -- **Phase 1 (Migration):** through **June 1, 2026** - - Upgrade SDKs/contracts, register your RP, and create v4 actions. - - New World ID users will have v3 and v4 credentials -- **Phase 2 (Transition):** **June 1, 2026** to **March 31, 2027** - - New users from this date will only be able to create 4.0 proofs. - - All users migrated to 4.0 -- **Phase 3 (v3 Cut-off):** from **April 1, 2027** onward - - v3 Proofs will no longer be generated by World ID +You can use IDKit 4.x even when a credential still uses a World ID 3.0 proof +flow. You do not need to downgrade the SDK. -If your rollout needs more time, extend Phase 2 and move `CD` later. +| Credential | Current compatibility behavior | +| --- | --- | +| Selfie Check (Beta) | Request it with `selfieCheckLegacy()`. It currently returns World ID 3.0 proofs; World ID 4.0 Selfie Check is not yet available. | +| [Device verification](/world-id/deprecations#device-verification) | `deviceLegacy()` is World ID 3.0-only and should be used only for existing integrations. World ID 4.0 does not have a Device preset; choose a current credential for new integrations. | ## Migration Path @@ -75,7 +73,8 @@ These apps have a single long-running action. #### Migration Flow Diagram -This diagram shows the three-phase migration process: preparation, gradual transition, and v3 cut-off. +This diagram shows an app-controlled migration: preparation, a compatibility +period, and the point when your app stops accepting World ID 3.0 proofs. ```mermaid sequenceDiagram @@ -88,7 +87,7 @@ sequenceDiagram RP->>Portal: Register for v4 Protocol RP->>Portal: Create v4 actions - Note over RP,User: Phase 2: Transition Date (TD = Migration Start Date) + Note over RP,User: Phase 2: Compatibility period (TD = migration start date) rect rgb(240, 248, 255) Note right of RP: Temporary compatibility mode (allow_legacy_proofs: true) RP->>User: Request proof (genesis_issued_at=TD, allow_legacy_proofs: true) @@ -102,7 +101,7 @@ sequenceDiagram RP->>RP: Store nullifier end - Note over RP,User: Phase 3: Cut-off of V3 + Note over RP,User: Phase 3: App cutover to v4 RP->>User: Request proof (allow_legacy_proofs: false, v4 only) alt User has v4 credential issued AFTER TD User->>RP: v4 proof + nullifier @@ -111,12 +110,13 @@ sequenceDiagram end ``` -**Summary:** During Phase 2, both v3 and v4 proofs are accepted. Phase 3 enforces v4-only. +**Summary:** During the compatibility period, the app accepts both v3 and v4 +proofs. At the app's cutover, it begins accepting only v4 proofs. - Users who have an old World ID will not be able to claim after Phase 3 as - their credential will be < TD. Because of this, Phase 2 should be - sufficiently long, up to one year. + Before switching your app to v4-only, confirm that the users you support can + produce the required v4 credentials. Choose the transition and cutover dates + for your own rollout rather than relying on a fixed global schedule. #### Step-by-step Migration Details @@ -179,7 +179,7 @@ These apps create multiple one-time actions. These actions are short lived. **Migration approach:** Migrate your SDK and Developer Portal account. Pick a new future action to start accepting only v4 proofs. #### Migration Flow Diagram -This diagram shows a simpler two-phase migration with a hard cutover. +This diagram shows a simpler two-step migration with an app-controlled cutover. ```mermaid sequenceDiagram @@ -192,7 +192,7 @@ sequenceDiagram RP->>Portal: Register for v4 Protocol RP->>Portal: Create v4 actions - Note over RP,User: Phase 2: Transition Date (TD) + Note over RP,User: Phase 2: App cutover (TD) rect rgb(255, 240, 245) Note right of RP: Hard Migration (allow_legacy_proofs: false) RP->>User: Request proof (genesis_issued_at=TD, allow_legacy_proofs: false) @@ -206,7 +206,7 @@ sequenceDiagram end ``` -**Summary:** During Phase 2, only accept v4 proofs for new actions. +**Summary:** At the app's cutover, new actions accept only v4 proofs. ### Recurring Verifications and New Credential Checks @@ -309,7 +309,7 @@ export async function proveSession(sessionId) { ### New Apps -Apps launched after v4 is fully released will not need to migrate. +New apps should start with IDKit 4.x and do not need a protocol migration path. ## Further Migration Details diff --git a/world-id/credentials/11.mdx b/world-id/credentials/11.mdx index aa0d119..c3e3fef 100644 --- a/world-id/credentials/11.mdx +++ b/world-id/credentials/11.mdx @@ -19,8 +19,6 @@ import { CredentialHero } from "/snippets/credential-hero.jsx"; issuerVerified={true} status="beta" id={11} - sybilResistance="some" - sybilResistanceDescription="Facial similarity checks provide some sybil resistance, but not as strong as Orb or NFC verification." validityPeriod="90 days" /> @@ -30,13 +28,18 @@ Selfie Check (Beta) uses the user's mobile device camera for liveness and facial similarity checks. It adds friction against automated and repeated account creation without requiring a Proof of Human. Unlike high-assurance Orb verification, Selfie Check does not provide a strict one-person-one-account guarantee. +It returns a proof of the completed check, not a numeric Sybil or uniqueness +score. Use Selfie Check (Beta) for: * **Liveness detection:** Confirm the user is a real person, not a spoof or injection attack. -* **Sybil resistance:** Make mass account creation harder through facial similarity checks. +* **Abuse resistance:** Add friction to automated and repeated account creation. * **Continuity:** Confirm a returning user is the same person who originally enrolled. +Selfie Check has a 90-day inactivity window. After 90 days without use, the +user completes the camera flow again before returning another proof. + Selfie Check (Beta) is access-gated. To use it, [request access](mailto:developers@toolsforhumanity.com) so the feature flag can be enabled for your app. @@ -57,8 +60,8 @@ Use IDKit to integrate Selfie Check into your application. 1. **Challenge:** The user initiates the flow on your app (Relying Party). 2. **Hand-off:** The user is redirected to World App. If they don't have World App installed, they are guided to download it and go straight into the Selfie Check experience. 3. **Enrollment/Auth:** - * **New User:** Prompts to "Take a selfie", then runs a liveness check and a uniqueness check against other faces. - * **Returning User:** Runs a quick Face Auth to verify continuity. + * **New User:** Enrolls with a selfie and liveness check. + * **Returning User:** Completes a short camera check to verify continuity. 4. **Success:** The user returns to your application with a verified credential. ## Next steps diff --git a/world-id/deprecations.mdx b/world-id/deprecations.mdx new file mode 100644 index 0000000..a39454c --- /dev/null +++ b/world-id/deprecations.mdx @@ -0,0 +1,18 @@ +--- +title: "Deprecations" +description: "Current World ID legacy features and their supported migration paths." +"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" +--- + +Use this page to track World ID features that are limited to legacy protocol +flows and the current migration guidance for new integrations. + +## Device verification + +**Status:** World ID 3.0 legacy only + +`deviceLegacy()` requests a World ID 3.0 Device proof for existing +integrations. World ID 4.0 does not have a Device preset. New integrations +should choose a current credential from the +[credential guide](/world-id/idkit/credentials). diff --git a/world-id/idkit/build-with-llms.mdx b/world-id/idkit/build-with-llms.mdx index 241861b..82e44a8 100644 --- a/world-id/idkit/build-with-llms.mdx +++ b/world-id/idkit/build-with-llms.mdx @@ -10,6 +10,9 @@ Create an app in the [Developer Portal](https://developer.world.org). You will n Prefer to integrate manually? Follow the [IDKit integration guide](/world-id/idkit/integrate) for the complete client, signing, verification, and testing flow. +If your coding assistant accepts a documentation index, give it the complete +[World documentation index](https://docs.world.org/llms.txt). + Copy this prompt and paste it into Codex, Claude, Cursor, or your preferred AI coding assistant: ```text title="Copy this prompt" From fa9f9b201d46394c7bc064822df9138f95f2287a Mon Sep 17 00:00:00 2001 From: Takis Kakalis <80459599+Takaros999@users.noreply.github.com> Date: Tue, 4 Aug 2026 15:19:29 -0700 Subject: [PATCH 2/3] docs: keep deprecation guidance in migration --- docs.json | 1 - world-id/4-0-migration.mdx | 2 +- world-id/deprecations.mdx | 18 ------------------ 3 files changed, 1 insertion(+), 20 deletions(-) delete mode 100644 world-id/deprecations.mdx diff --git a/docs.json b/docs.json index 64faf99..a4aa0cd 100644 --- a/docs.json +++ b/docs.json @@ -103,7 +103,6 @@ "group": "Migration", "pages": [ "world-id/4-0-migration", - "world-id/deprecations", "world-id/from-idkit-standalone" ] }, diff --git a/world-id/4-0-migration.mdx b/world-id/4-0-migration.mdx index 13cea3f..82a6f50 100644 --- a/world-id/4-0-migration.mdx +++ b/world-id/4-0-migration.mdx @@ -51,7 +51,7 @@ flow. You do not need to downgrade the SDK. | Credential | Current compatibility behavior | | --- | --- | | Selfie Check (Beta) | Request it with `selfieCheckLegacy()`. It currently returns World ID 3.0 proofs; World ID 4.0 Selfie Check is not yet available. | -| [Device verification](/world-id/deprecations#device-verification) | `deviceLegacy()` is World ID 3.0-only and should be used only for existing integrations. World ID 4.0 does not have a Device preset; choose a current credential for new integrations. | +| Device verification | `deviceLegacy()` is World ID 3.0-only and should be used only for existing integrations. World ID 4.0 does not have a Device preset; choose a current credential for new integrations. | ## Migration Path diff --git a/world-id/deprecations.mdx b/world-id/deprecations.mdx deleted file mode 100644 index a39454c..0000000 --- a/world-id/deprecations.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: "Deprecations" -description: "Current World ID legacy features and their supported migration paths." -"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" ---- - -Use this page to track World ID features that are limited to legacy protocol -flows and the current migration guidance for new integrations. - -## Device verification - -**Status:** World ID 3.0 legacy only - -`deviceLegacy()` requests a World ID 3.0 Device proof for existing -integrations. World ID 4.0 does not have a Device preset. New integrations -should choose a current credential from the -[credential guide](/world-id/idkit/credentials). From ff8abda0488b1997b45c1b202b56345dac7997b2 Mon Sep 17 00:00:00 2001 From: Takis Kakalis <80459599+Takaros999@users.noreply.github.com> Date: Tue, 4 Aug 2026 15:33:53 -0700 Subject: [PATCH 3/3] docs: simplify legacy credential guidance --- world-id/4-0-migration.mdx | 11 +---------- world-id/idkit/credentials.mdx | 2 +- 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/world-id/4-0-migration.mdx b/world-id/4-0-migration.mdx index 82a6f50..354f7b7 100644 --- a/world-id/4-0-migration.mdx +++ b/world-id/4-0-migration.mdx @@ -43,16 +43,7 @@ Adopting World ID 4.0 requires upgrading to IDKit 4.x, which introduces major br For details and example code, see the [IDKit 4.0 integration guide](/world-id/idkit/integrate). -### Legacy credential compatibility - -You can use IDKit 4.x even when a credential still uses a World ID 3.0 proof -flow. You do not need to downgrade the SDK. - -| Credential | Current compatibility behavior | -| --- | --- | -| Selfie Check (Beta) | Request it with `selfieCheckLegacy()`. It currently returns World ID 3.0 proofs; World ID 4.0 Selfie Check is not yet available. | -| Device verification | `deviceLegacy()` is World ID 3.0-only and should be used only for existing integrations. World ID 4.0 does not have a Device preset; choose a current credential for new integrations. | - +See [Configure Credentials](/world-id/idkit/credentials) to choose a World ID 4.0 credential, or [Other legacy presets](/world-id/idkit/credentials#other-legacy-presets) to maintain an existing World ID 3.0 integration. ## Migration Path diff --git a/world-id/idkit/credentials.mdx b/world-id/idkit/credentials.mdx index b9d13e7..0dddb5d 100644 --- a/world-id/idkit/credentials.mdx +++ b/world-id/idkit/credentials.mdx @@ -280,7 +280,7 @@ These presets only return World ID 3.0 proofs. Use them for existing integration deviceLegacy - At least a Device verification. Returns the user's highest legacy credential: Device, Document, Secure Document, or Orb. + Deprecated. Keep deviceLegacy only for existing Device integrations. For new integrations, use Selfie Check (Beta).