From 8d88f907fd151cae6efdeb5c3b3e0d6f7772c2a5 Mon Sep 17 00:00:00 2001 From: Kartike Chawla Date: Tue, 13 Oct 2026 16:23:32 -0700 Subject: [PATCH 1/3] docs(world-id): require constraints for session proofs --- world-id/SKILL.md | 8 ++++++-- world-id/credentials/11.mdx | 4 +++- world-id/idkit/credentials.mdx | 9 ++++++--- world-id/idkit/javascript.mdx | 5 ++++- world-id/idkit/mini-apps.mdx | 4 +++- world-id/idkit/react.mdx | 9 ++++++++- world-id/idkit/session-proofs.mdx | 21 +++++++++++++++------ 7 files changed, 45 insertions(+), 15 deletions(-) diff --git a/world-id/SKILL.md b/world-id/SKILL.md index 9004997..4d95aba 100644 --- a/world-id/SKILL.md +++ b/world-id/SKILL.md @@ -112,7 +112,11 @@ A user can have only one [NFC Credential](https://docs.world.org/world-id/creden ### Selfie Check For repeated Selfie Check verification, use `IDKit.createSession` followed by -`IDKit.proveSession` with `.preset(selfieCheck())`. +`IDKit.proveSession` with `.constraints(CredentialRequest("selfie"))`. +In IDKit 4.4.0, session proofs require constraints; presets, including +`selfieCheck()`, are not supported. For React, use +`constraints={CredentialRequest("selfie")}` on `IDKitSessionWidget` or +`constraints: CredentialRequest("selfie")` in `useIDKitSession`. Save the verified `session_id` against the application account and require that same session on later checks; enforce per-proof replay protection. @@ -136,7 +140,7 @@ The full code for each step is at [https://docs.world.org/world-id/idkit/integra The checklist below describes uniqueness requests. For session integrations, adapt it using `/world-id/idkit/session-proofs`: omit action setup and omit the action from RP signing, -use `IDKitSessionWidget` or the session builders with presets, and replace +use `IDKitSessionWidget` or the session builders with constraints, and replace uniqueness-nullifier storage with verified account-to-session binding and per-proof replay protection. Test both creation and proving the saved session. diff --git a/world-id/credentials/11.mdx b/world-id/credentials/11.mdx index 26be43e..1d66638 100644 --- a/world-id/credentials/11.mdx +++ b/world-id/credentials/11.mdx @@ -124,7 +124,9 @@ guarantee. ## How it works -Use the `selfieCheck` preset in IDKit to integrate Proof of Presence into your application. +For session proofs, use `.constraints(CredentialRequest("selfie"))` in IDKit. +For one-time uniqueness requests, use `.preset(selfieCheck())`. See +[Configure Credentials](/world-id/idkit/credentials#selfie-check) for examples. * **On mobile (iOS/Android):** Use IDKit to generate a deep link and attach it to a "Verify" CTA. When the user taps it, they are redirected to World ID App to complete Proof of Presence. * **On desktop:** Use IDKit to generate a QR code and display it to the user. When the user scans it with their mobile device camera, World ID App launches and guides them through Proof of Presence. diff --git a/world-id/idkit/credentials.mdx b/world-id/idkit/credentials.mdx index b0501fe..a7fe1d2 100644 --- a/world-id/idkit/credentials.mdx +++ b/world-id/idkit/credentials.mdx @@ -109,7 +109,7 @@ const preset = passport({ signal: "user-123" }); ## Proof of Presence (Selfie Check) -Use `selfieCheck()` with [session proofs](/world-id/idkit/session-proofs) to verify +Use `CredentialRequest("selfie")` with [session proofs](/world-id/idkit/session-proofs) to verify users when they first arrive and when they return. Create a session once, save its verified `session_id`, then prove that same session on later checks. @@ -117,14 +117,17 @@ Anyone with World ID App can complete the flow—no Orb or document credential i required. ```typescript -import { IDKit, selfieCheck } from "@worldcoin/idkit-core"; +import { IDKit, CredentialRequest } from "@worldcoin/idkit-core"; const request = await IDKit.createSession({ app_id: "app_xxxxx", rp_context, -}).preset(selfieCheck()); +}).constraints(CredentialRequest("selfie")); ``` +In IDKit 4.4.0, session creation and verification require `.constraints(...)`; +`.preset(selfieCheck())` is only supported for request flows. + Follow the [session guide](/world-id/idkit/session-proofs) for the complete create-and-return flow. Forward the complete result, including `sybil_score` and `integrity_bundle`, to your backend and only use the score after verification diff --git a/world-id/idkit/javascript.mdx b/world-id/idkit/javascript.mdx index 03d8ce6..ccd629e 100644 --- a/world-id/idkit/javascript.mdx +++ b/world-id/idkit/javascript.mdx @@ -28,10 +28,13 @@ yarn add @worldcoin/idkit-core - `IDKit.request(config)` for uniqueness proofs - `IDKit.requestWithInviteCode(config)` for invite-code mode +- `IDKit.createSession(config)` and `IDKit.proveSession(sessionId, config)` for session proofs - `proofOfHuman`, `passport`, `selfieCheck`, and `identityCheck` for current presets - `orbLegacy`, `secureDocumentLegacy`, `documentLegacy`, and `deviceLegacy` for legacy presets -Each entry point returns a builder. Finalize it with `.preset(...)`. +Request builders accept `.preset(...)` or `.constraints(...)`. In IDKit 4.4.0, +session builders require `.constraints(...)` and do not support presets. See +[Session proofs](/world-id/idkit/session-proofs) for examples. ## Request config diff --git a/world-id/idkit/mini-apps.mdx b/world-id/idkit/mini-apps.mdx index b8166c3..6c75855 100644 --- a/world-id/idkit/mini-apps.mdx +++ b/world-id/idkit/mini-apps.mdx @@ -41,7 +41,9 @@ The Mini-App-specific details: | Passport-backed checks | `passport` | For repeated Selfie Check verification of returning users, use -[session proofs](/world-id/idkit/session-proofs) with the `selfieCheck()` preset. +[session proofs](/world-id/idkit/session-proofs) with +`constraints={CredentialRequest("selfie")}` on `IDKitSessionWidget`. Session flows +require constraints in IDKit 4.4.0; the `selfieCheck()` preset is for request flows. Check out this [page](/world-id/idkit/credentials) to learn about the different World ID credentials and which preset to use for each. diff --git a/world-id/idkit/react.mdx b/world-id/idkit/react.mdx index 331a54b..5d986c8 100644 --- a/world-id/idkit/react.mdx +++ b/world-id/idkit/react.mdx @@ -193,9 +193,16 @@ Swap the component and preset. Props, callbacks, and backend verification stay t Session verification uses `IDKitSessionWidget` (controlled) or `useIDKitSession` (headless); `onSuccess` returns an `IDKitResultSession`. Both share the request flows' widget callbacks and hook-result fields — including `onError(errorCode, debugReport?)` and `getDebugReport()`. +In IDKit 4.4.0, both require `constraints` and do not support `preset`. For Selfie +Check, import `CredentialRequest` from `@worldcoin/idkit` and pass +`constraints={CredentialRequest("selfie")}` to the widget, or +`constraints: CredentialRequest("selfie")` to the hook. See +[Session proofs](/world-id/idkit/session-proofs) for creation and returning-user checks. + ## Presets -React hooks/widgets take `preset` directly in config. +Request hooks/widgets take `preset` directly in config. Session hooks/widgets +require `constraints` as described above. ## Localization and UX notes diff --git a/world-id/idkit/session-proofs.mdx b/world-id/idkit/session-proofs.mdx index a8d9404..4e4f642 100644 --- a/world-id/idkit/session-proofs.mdx +++ b/world-id/idkit/session-proofs.mdx @@ -31,6 +31,14 @@ Generate fresh [RP signatures](/world-id/idkit/signatures) for session creation each subsequent check. Call `signRequest({ signingKeyHex })` without an `action`; session requests do not take an action or support legacy proofs. + + In IDKit 4.4.0, session proofs require `.constraints(...)`. Presets, including + `selfieCheck()`, are not supported by `IDKit.createSession` or + `IDKit.proveSession`. For Selfie Check, use + `.constraints(CredentialRequest("selfie"))`. React session widgets and hooks + likewise require `constraints` instead of `preset`. + + The examples assume `app_id` comes from your Portal configuration and `rp_context` contains the fresh signature returned by your backend. Use a new `rp_context` for each example invocation. @@ -38,13 +46,13 @@ each example invocation. ## Create a session ```typescript -import { IDKit, selfieCheck } from "@worldcoin/idkit-core"; +import { IDKit, CredentialRequest } from "@worldcoin/idkit-core"; const request = await IDKit.createSession({ app_id, rp_context, environment: "production", -}).preset(selfieCheck()); +}).constraints(CredentialRequest("selfie")); // Display request.connectorURI as a link or QR code, then wait for the user. const completion = await request.pollUntilCompletion({ timeout: 120_000 }); @@ -54,7 +62,7 @@ if (!completion.success) throw new Error(completion.error); // Save its session_id against the account only after verification succeeds. ``` -The `selfieCheck()` preset selects the Selfie Check credential. See +`CredentialRequest("selfie")` selects the Selfie Check credential. See [Configure Credentials](/world-id/idkit/credentials) for credential options. Your backend must verify the complete result before saving its `session_id`. @@ -68,13 +76,13 @@ Load the saved session ID from your backend for the account being verified, and obtain a fresh RP signature. Prove that existing session: ```typescript -import { IDKit, selfieCheck } from "@worldcoin/idkit-core"; +import { IDKit, CredentialRequest } from "@worldcoin/idkit-core"; const request = await IDKit.proveSession(savedSessionId, { app_id, rp_context, environment: "production", -}).preset(selfieCheck()); +}).constraints(CredentialRequest("selfie")); const completion = await request.pollUntilCompletion({ timeout: 120_000 }); if (!completion.success) throw new Error(completion.error); @@ -88,6 +96,7 @@ Preserve it unchanged. Creating a new session on each visit does not establish continuity with the account's existing session. For React, use `IDKitSessionWidget` with -`preset={selfieCheck()}`. Omit `existing_session_id` for +`constraints={CredentialRequest("selfie")}`; import both from `@worldcoin/idkit`. +Omit `existing_session_id` for creation and set it to the saved session ID for subsequent checks. The widget's `handleVerify` callback should call your backend before `onSuccess` grants access. From 112569d7bb7409d0f579195d3b24e56d6b88f90c Mon Sep 17 00:00:00 2001 From: Kartike Chawla Date: Tue, 13 Oct 2026 16:28:34 -0700 Subject: [PATCH 2/3] docs(world-id): narrow session fix to broken examples --- world-id/SKILL.md | 2 +- world-id/credentials/11.mdx | 4 +--- world-id/idkit/credentials.mdx | 2 +- world-id/idkit/javascript.mdx | 5 +---- world-id/idkit/mini-apps.mdx | 4 +--- world-id/idkit/react.mdx | 9 +-------- world-id/idkit/session-proofs.mdx | 2 +- 7 files changed, 7 insertions(+), 21 deletions(-) diff --git a/world-id/SKILL.md b/world-id/SKILL.md index 4d95aba..b5cbd58 100644 --- a/world-id/SKILL.md +++ b/world-id/SKILL.md @@ -113,7 +113,7 @@ A user can have only one [NFC Credential](https://docs.world.org/world-id/creden For repeated Selfie Check verification, use `IDKit.createSession` followed by `IDKit.proveSession` with `.constraints(CredentialRequest("selfie"))`. -In IDKit 4.4.0, session proofs require constraints; presets, including +Session proofs currently require constraints; presets, including `selfieCheck()`, are not supported. For React, use `constraints={CredentialRequest("selfie")}` on `IDKitSessionWidget` or `constraints: CredentialRequest("selfie")` in `useIDKitSession`. diff --git a/world-id/credentials/11.mdx b/world-id/credentials/11.mdx index 1d66638..26be43e 100644 --- a/world-id/credentials/11.mdx +++ b/world-id/credentials/11.mdx @@ -124,9 +124,7 @@ guarantee. ## How it works -For session proofs, use `.constraints(CredentialRequest("selfie"))` in IDKit. -For one-time uniqueness requests, use `.preset(selfieCheck())`. See -[Configure Credentials](/world-id/idkit/credentials#selfie-check) for examples. +Use the `selfieCheck` preset in IDKit to integrate Proof of Presence into your application. * **On mobile (iOS/Android):** Use IDKit to generate a deep link and attach it to a "Verify" CTA. When the user taps it, they are redirected to World ID App to complete Proof of Presence. * **On desktop:** Use IDKit to generate a QR code and display it to the user. When the user scans it with their mobile device camera, World ID App launches and guides them through Proof of Presence. diff --git a/world-id/idkit/credentials.mdx b/world-id/idkit/credentials.mdx index a7fe1d2..f36c6f1 100644 --- a/world-id/idkit/credentials.mdx +++ b/world-id/idkit/credentials.mdx @@ -125,7 +125,7 @@ const request = await IDKit.createSession({ }).constraints(CredentialRequest("selfie")); ``` -In IDKit 4.4.0, session creation and verification require `.constraints(...)`; +Session creation and verification currently require `.constraints(...)`; `.preset(selfieCheck())` is only supported for request flows. Follow the [session guide](/world-id/idkit/session-proofs) for the complete diff --git a/world-id/idkit/javascript.mdx b/world-id/idkit/javascript.mdx index ccd629e..03d8ce6 100644 --- a/world-id/idkit/javascript.mdx +++ b/world-id/idkit/javascript.mdx @@ -28,13 +28,10 @@ yarn add @worldcoin/idkit-core - `IDKit.request(config)` for uniqueness proofs - `IDKit.requestWithInviteCode(config)` for invite-code mode -- `IDKit.createSession(config)` and `IDKit.proveSession(sessionId, config)` for session proofs - `proofOfHuman`, `passport`, `selfieCheck`, and `identityCheck` for current presets - `orbLegacy`, `secureDocumentLegacy`, `documentLegacy`, and `deviceLegacy` for legacy presets -Request builders accept `.preset(...)` or `.constraints(...)`. In IDKit 4.4.0, -session builders require `.constraints(...)` and do not support presets. See -[Session proofs](/world-id/idkit/session-proofs) for examples. +Each entry point returns a builder. Finalize it with `.preset(...)`. ## Request config diff --git a/world-id/idkit/mini-apps.mdx b/world-id/idkit/mini-apps.mdx index 6c75855..b8166c3 100644 --- a/world-id/idkit/mini-apps.mdx +++ b/world-id/idkit/mini-apps.mdx @@ -41,9 +41,7 @@ The Mini-App-specific details: | Passport-backed checks | `passport` | For repeated Selfie Check verification of returning users, use -[session proofs](/world-id/idkit/session-proofs) with -`constraints={CredentialRequest("selfie")}` on `IDKitSessionWidget`. Session flows -require constraints in IDKit 4.4.0; the `selfieCheck()` preset is for request flows. +[session proofs](/world-id/idkit/session-proofs) with the `selfieCheck()` preset. Check out this [page](/world-id/idkit/credentials) to learn about the different World ID credentials and which preset to use for each. diff --git a/world-id/idkit/react.mdx b/world-id/idkit/react.mdx index 5d986c8..331a54b 100644 --- a/world-id/idkit/react.mdx +++ b/world-id/idkit/react.mdx @@ -193,16 +193,9 @@ Swap the component and preset. Props, callbacks, and backend verification stay t Session verification uses `IDKitSessionWidget` (controlled) or `useIDKitSession` (headless); `onSuccess` returns an `IDKitResultSession`. Both share the request flows' widget callbacks and hook-result fields — including `onError(errorCode, debugReport?)` and `getDebugReport()`. -In IDKit 4.4.0, both require `constraints` and do not support `preset`. For Selfie -Check, import `CredentialRequest` from `@worldcoin/idkit` and pass -`constraints={CredentialRequest("selfie")}` to the widget, or -`constraints: CredentialRequest("selfie")` to the hook. See -[Session proofs](/world-id/idkit/session-proofs) for creation and returning-user checks. - ## Presets -Request hooks/widgets take `preset` directly in config. Session hooks/widgets -require `constraints` as described above. +React hooks/widgets take `preset` directly in config. ## Localization and UX notes diff --git a/world-id/idkit/session-proofs.mdx b/world-id/idkit/session-proofs.mdx index 4e4f642..4258186 100644 --- a/world-id/idkit/session-proofs.mdx +++ b/world-id/idkit/session-proofs.mdx @@ -32,7 +32,7 @@ each subsequent check. Call `signRequest({ signingKeyHex })` without an `action` session requests do not take an action or support legacy proofs. - In IDKit 4.4.0, session proofs require `.constraints(...)`. Presets, including + Session proofs currently require `.constraints(...)`. Presets, including `selfieCheck()`, are not supported by `IDKit.createSession` or `IDKit.proveSession`. For Selfie Check, use `.constraints(CredentialRequest("selfie"))`. React session widgets and hooks From 3271247c61c40d5cdb996c68dcb46ce7ac366a7a Mon Sep 17 00:00:00 2001 From: Kartike Chawla Date: Wed, 14 Oct 2026 11:23:53 -0700 Subject: [PATCH 3/3] docs(world-id): clarify released session API guidance --- world-id/SKILL.md | 3 +-- world-id/idkit/credentials.mdx | 3 --- world-id/idkit/mini-apps.mdx | 3 ++- world-id/idkit/session-proofs.mdx | 11 ++++------- 4 files changed, 7 insertions(+), 13 deletions(-) diff --git a/world-id/SKILL.md b/world-id/SKILL.md index b5cbd58..48468f3 100644 --- a/world-id/SKILL.md +++ b/world-id/SKILL.md @@ -113,8 +113,7 @@ A user can have only one [NFC Credential](https://docs.world.org/world-id/creden For repeated Selfie Check verification, use `IDKit.createSession` followed by `IDKit.proveSession` with `.constraints(CredentialRequest("selfie"))`. -Session proofs currently require constraints; presets, including -`selfieCheck()`, are not supported. For React, use +IDKit 4.4.0 requires constraints for sessions. For React, use `constraints={CredentialRequest("selfie")}` on `IDKitSessionWidget` or `constraints: CredentialRequest("selfie")` in `useIDKitSession`. Save the verified `session_id` against the application account diff --git a/world-id/idkit/credentials.mdx b/world-id/idkit/credentials.mdx index f36c6f1..4d463b1 100644 --- a/world-id/idkit/credentials.mdx +++ b/world-id/idkit/credentials.mdx @@ -125,9 +125,6 @@ const request = await IDKit.createSession({ }).constraints(CredentialRequest("selfie")); ``` -Session creation and verification currently require `.constraints(...)`; -`.preset(selfieCheck())` is only supported for request flows. - Follow the [session guide](/world-id/idkit/session-proofs) for the complete create-and-return flow. Forward the complete result, including `sybil_score` and `integrity_bundle`, to your backend and only use the score after verification diff --git a/world-id/idkit/mini-apps.mdx b/world-id/idkit/mini-apps.mdx index b8166c3..72b1e23 100644 --- a/world-id/idkit/mini-apps.mdx +++ b/world-id/idkit/mini-apps.mdx @@ -41,7 +41,8 @@ The Mini-App-specific details: | Passport-backed checks | `passport` | For repeated Selfie Check verification of returning users, use -[session proofs](/world-id/idkit/session-proofs) with the `selfieCheck()` preset. +[session proofs](/world-id/idkit/session-proofs) with +`constraints={CredentialRequest("selfie")}` on `IDKitSessionWidget`. Check out this [page](/world-id/idkit/credentials) to learn about the different World ID credentials and which preset to use for each. diff --git a/world-id/idkit/session-proofs.mdx b/world-id/idkit/session-proofs.mdx index 4258186..8e07609 100644 --- a/world-id/idkit/session-proofs.mdx +++ b/world-id/idkit/session-proofs.mdx @@ -32,11 +32,8 @@ each subsequent check. Call `signRequest({ signingKeyHex })` without an `action` session requests do not take an action or support legacy proofs. - Session proofs currently require `.constraints(...)`. Presets, including - `selfieCheck()`, are not supported by `IDKit.createSession` or - `IDKit.proveSession`. For Selfie Check, use - `.constraints(CredentialRequest("selfie"))`. React session widgets and hooks - likewise require `constraints` instead of `preset`. + In IDKit 4.4.0, session builders require `.constraints(...)`; `.preset(...)` + throws an error. React session widgets and hooks also require `constraints`. The examples assume `app_id` comes from your Portal configuration and `rp_context` @@ -97,6 +94,6 @@ continuity with the account's existing session. For React, use `IDKitSessionWidget` with `constraints={CredentialRequest("selfie")}`; import both from `@worldcoin/idkit`. -Omit `existing_session_id` for -creation and set it to the saved session ID for subsequent checks. The widget's +Omit `existing_session_id` for creation and set it to the saved session ID for +subsequent checks. The widget's `handleVerify` callback should call your backend before `onSuccess` grants access.