diff --git a/docs.json b/docs.json index c4001f9..ddb4aa4 100644 --- a/docs.json +++ b/docs.json @@ -71,6 +71,7 @@ "group": "IDKit", "pages": [ "world-id/idkit/integrate", + "world-id/idkit/session-proofs", "world-id/idkit/verification-flows", "world-id/idkit/credentials", "world-id/idkit/mini-apps", diff --git a/openapi/developer-portal.json b/openapi/developer-portal.json index 8acb393..738f095 100644 --- a/openapi/developer-portal.json +++ b/openapi/developer-portal.json @@ -742,6 +742,32 @@ ] } }, + "selfie_check_v4": { + "summary": "Selfie Check", + "value": { + "protocol_version": "4.0", + "nonce": "0xabc123", + "action": "selfie-check-2026-09-02", + "integrity_bundle": { + "version": 2, + "signature_format": "apple_app_attest", + "timestamp": 1788302923, + "signature": "a1b2c3d4", + "jwt": "eyJ..." + }, + "responses": [ + { + "identifier": "selfie", + "issuer_schema_id": 11, + "nullifier": "0x2bf8406809dcefb1486dadc96c0a897db9bab002053054cf64272db512c6fbd8", + "expires_at_min": 1788302888, + "proof": ["0x111", "0x222", "0x333", "0x444", "0x555"], + "signal_hash": "0x0", + "sybil_score": 10 + } + ] + } + }, "session_v4": { "summary": "Session proof (protocol 4.0)", "value": { @@ -861,7 +887,7 @@ "device", "selfie" ], - "description": "The legacy verification level. Use `selfie` for Selfie Check (Beta). The historical `face` value remains accepted for backward compatibility and behaves the same as `selfie`." + "description": "The legacy verification level. Use `selfie` for Selfie Check. The historical `face` value remains accepted for backward compatibility and behaves the same as `selfie`." }, "action": { "type": "string", @@ -1250,6 +1276,33 @@ "additionalProperties": true, "description": "Pass-through GraphQL response. Usually includes `data` and optionally `errors`." }, + "IntegrityBundle": { + "type": "object", + "required": ["version", "signature_format", "timestamp", "signature", "jwt"], + "description": "World ID App integrity attestation. Selfie Check responses with `issuer_schema_id: 11` require version 2, which covers the disclosed `sybil_score`.", + "properties": { + "version": { + "type": "integer", + "enum": [1, 2] + }, + "signature_format": { + "type": "string", + "enum": ["apple_app_attest", "android_keystore"] + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "signature": { + "type": "string", + "description": "Hex-encoded device signature." + }, + "jwt": { + "type": "string", + "description": "Attestation Gateway JWT used to verify the signing key." + } + } + }, "VerifyV4Request": { "description": "Choose one request type.", "oneOf": [ @@ -1303,6 +1356,9 @@ "enum": ["production", "staging"], "default": "production" }, + "integrity_bundle": { + "$ref": "#/components/schemas/IntegrityBundle" + }, "responses": { "type": "array", "minItems": 1, @@ -1312,7 +1368,7 @@ }, "user_presence_completed": { "type": "boolean", - "description": "Whether World App completed the requested user-presence check. IDKit always sends it; treat a missing value as false." + "description": "Whether World App completed the requested user-presence check. IDKit includes this field only when `require_user_presence` was true in the request." } } }, @@ -1337,9 +1393,17 @@ }, "environment": { "type": "string", - "enum": ["production", "staging"], + "enum": ["production", "staging", "sandbox"], "default": "production" }, + "integrity_bundle": { + "description": "Required with version 2 when any response item is a Selfie Check credential (`issuer_schema_id: 11`).", + "allOf": [ + { + "$ref": "#/components/schemas/IntegrityBundle" + } + ] + }, "responses": { "type": "array", "minItems": 1, @@ -1349,7 +1413,7 @@ }, "user_presence_completed": { "type": "boolean", - "description": "Whether World App completed the requested user-presence check. IDKit always sends it; treat a missing value as false." + "description": "Whether World App completed the requested user-presence check. IDKit includes this field only when `require_user_presence` was true in the request." } } }, @@ -1373,9 +1437,17 @@ }, "environment": { "type": "string", - "enum": ["production", "staging"], + "enum": ["production", "staging", "sandbox"], "default": "production" }, + "integrity_bundle": { + "description": "Required with version 2 when any response item is a Selfie Check credential (`issuer_schema_id: 11`).", + "allOf": [ + { + "$ref": "#/components/schemas/IntegrityBundle" + } + ] + }, "responses": { "type": "array", "minItems": 1, @@ -1385,7 +1457,7 @@ }, "user_presence_completed": { "type": "boolean", - "description": "Whether World App completed the requested user-presence check. IDKit always sends it; treat a missing value as false." + "description": "Whether World App completed the requested user-presence check. IDKit includes this field only when `require_user_presence` was true in the request." } } }, @@ -1395,7 +1467,7 @@ "properties": { "identifier": { "type": "string", - "description": "Credential identifier returned by IDKit (for example, `orb` or `selfie`). Use `selfie` for Selfie Check (Beta); the historical `face` value remains accepted as a backward-compatible alias." + "description": "Credential identifier returned by IDKit (for example, `orb` or `selfie`). Use `selfie` for Selfie Check; the historical `face` value remains accepted as a backward-compatible alias." }, "signal_hash": { "type": "string", @@ -1451,6 +1523,11 @@ "type": "string" }, "description": "Exactly 5 hex elements (4 compressed proof elements + Merkle root)." + }, + "sybil_score": { + "type": "integer", + "minimum": 0, + "description": "Versioned Selfie Check risk signal represented as an integer. Required only when `issuer_schema_id` is 11." } } }, @@ -1493,6 +1570,11 @@ "items": { "type": "string" } + }, + "sybil_score": { + "type": "integer", + "minimum": 0, + "description": "Versioned Selfie Check risk signal represented as an integer. Required only when `issuer_schema_id` is 11." } } }, diff --git a/snippets/idkit-response.mdx b/snippets/idkit-response.mdx index 200baa1..1fc4feb 100644 --- a/snippets/idkit-response.mdx +++ b/snippets/idkit-response.mdx @@ -13,8 +13,7 @@ "merkle_root": "0x0abc123...root_hash", "nullifier": "0x04e5f6...nullifier_hash" } - ], - "user_presence_completed": false + ] } ``` @@ -33,8 +32,34 @@ "issuer_schema_id": 1, "expires_at_min": 1756166400 } - ], - "user_presence_completed": false + ] +} +``` + +```json title="Selfie Check" +{ + "protocol_version": "4.0", + "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "action": "selfie-check-2026-09-02", + "environment": "production", + "integrity_bundle": { + "version": 2, + "signature_format": "apple_app_attest", + "timestamp": 1788302923, + "signature": "a1b2c3d4...device_signature", + "jwt": "eyJ...attestation_jwt" + }, + "responses": [ + { + "identifier": "selfie", + "signal_hash": "0x0", + "proof": ["0x1a2b...", "0x3c4d...", "0x5e6f...", "0x7a8b...", "0x9c0d..."], + "nullifier": "0x04e5f6...rp_scoped_nullifier", + "issuer_schema_id": 11, + "expires_at_min": 1788302888, + "sybil_score": 10 + } + ] } ``` @@ -53,8 +78,7 @@ "issuer_schema_id": 1, "expires_at_min": 1756166400 } - ], - "user_presence_completed": false + ] } ``` diff --git a/world-id/4-0-migration.mdx b/world-id/4-0-migration.mdx index 354f7b7..85788d5 100644 --- a/world-id/4-0-migration.mdx +++ b/world-id/4-0-migration.mdx @@ -205,98 +205,9 @@ For apps that rely on unlimited verifications of the same action. **Examples:** Partners that check for users who've added new credentials. Apps that allow users to verify before each claim using the same action (note this is an anti-pattern of World ID). -**Migration approach:** Migrate to [Session Proofs](https://github.com/worldcoin/world-id-protocol/blob/main/docs/world-id-4-specs/README.md#session-proofs), which let you verify credentials over a period of time while ensuring it's the same user. The session ID returned in the proof becomes the long-lived stable identifier instead. +**Migration approach:** Use [session proofs](/world-id/idkit/session-proofs). Create a session once, save the verified `session_id` against the application account, and prove that same session for later checks. The session guide covers creation, returning-user verification, backend checks, and replay protection. -#### Migration Flow Diagram - -This diagram shows how Session Proofs provide a stable identifier across multiple verifications. - -```mermaid -sequenceDiagram - participant RP as Relying Party - participant Portal as Developer Portal - participant User as User/Authenticator - - Note over RP,User: Phase 1: Setup - RP->>Portal: Register app for v4 Protocol - RP->>RP: Update to IDKit.Session - - Note over RP,User: Phase 2: Initial Session Enrollment - rect rgb(240, 248, 255) - RP->>User: IDKit.Session request - User->>RP: proof + sessionId - RP->>RP: Store sessionId (replaces nullifier as stable identifier) - end - - Note over RP,User: Phase 3: Subsequent Interactions - rect rgb(240, 255, 240) - RP->>User: Session proof request (sessionId) - User->>RP: proof + sessionNullifier + sessionId - RP->>RP: Verify sessionId matches stored value - end - - Note over RP,User: Example: Credential Upgrade - rect rgb(255, 250, 240) - RP->>User: Session proof request (sessionId, credential=Document) - User->>RP: proof + sessionNullifier + sessionId - RP->>RP: If the sessionID doesn't match the proof will fail - end -``` - -**Summary:** Session IDs provide continuity across verifications, replacing nullifiers as the stable identifier. - -```jsx Creating a session -export async function createSession() { - const rpContext = await fetch("/api/worldid/rp-context").then((r) => r.json()); - - const request = await IDKit.createSession({ - app_id: APP_ID, - rp_context: rpContext, - }).constraints(any(CredentialRequest("proof_of_human"))); - - // Web only: render this QR URL - const qrUrl = request.connectorURI; - - const completion = await request.pollUntilCompletion({ timeout: 120000 }); - if (!completion.success) throw new Error(completion.error); - - const verify = await fetch("/api/worldid/verify", { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify(completion.result), - }).then((r) => r.json()); - - if (!verify.success) throw new Error("Verification failed"); - - // IMPORTANT: Save this in order to prove future sessions for the same user - return completion.result.session_id; -} -``` - -```tsx Proving a session -// sessionId should have been saved when you created the session -export async function proveSession(sessionId) { - const rpContext = await fetch("/api/worldid/rp-context").then((r) => r.json()); - - const request = await IDKit.proveSession(sessionId, { - app_id: APP_ID, - rp_context: rpContext, - }).constraints(any(CredentialRequest("proof_of_human"))); - - const completion = await request.pollUntilCompletion({ timeout: 120000 }); - if (!completion.success) throw new Error(completion.error); - - const verify = await fetch("/api/worldid/verify", { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify(completion.result), - }).then((r) => r.json()); - - if (!verify.success) throw new Error("Verification failed"); - - return verify; -} -``` +Do not carry over a uniqueness nullifier as a persistent user identifier. Session responses use `session_nullifier` for per-proof replay protection and `session_id` for continuity. ### New Apps diff --git a/world-id/SKILL.md b/world-id/SKILL.md index 3a66cee..ad7884f 100644 --- a/world-id/SKILL.md +++ b/world-id/SKILL.md @@ -1,7 +1,7 @@ --- name: world-id-integration description: | - Use this skill when adding, upgrading, debugging, or testing World ID verification with IDKit in a new or existing web or mobile app. Covers Proof of Human, passport/document, Selfie Check (Beta), and session/sign-in flows; Developer Portal app, RP, and action setup; server-side signing and proof verification; environment matching; nullifier replay protection; and launch testing. Trigger when the user asks to add World ID, verify humans, stop bots or multi-accounting, add Sybil resistance, or mentions IDKit, Orb, World ID proof flows, World App proof flows, @worldcoin/idkit, signing keys, rp_id, or app_id. + Use this skill when adding, upgrading, debugging, or testing World ID verification with IDKit in a new or existing web or mobile app. Covers Proof of Human, passport/document, Selfie Check, and session/sign-in flows; Developer Portal app, RP, and action setup; server-side signing and proof verification; environment matching; nullifier replay protection; and launch testing. Trigger when the user asks to add World ID, verify humans, stop bots or multi-accounting, add Sybil resistance, or mentions IDKit, Orb, World ID proof flows, World App proof flows, @worldcoin/idkit, signing keys, rp_id, or app_id. version: 0.1.0 metadata: author: worldcoin @@ -38,7 +38,7 @@ Before changing code or creating Portal resources: - target environment and test path: staging simulator, production World ID, or both - Developer Portal MCP connection - whether an RP signing key already exists in a server-side secret store - - requested credential policy, feature access (especially Selfie Check (Beta)), and whether legacy proof fallback is needed + - requested credential policy and whether legacy proof fallback is needed 3. Report a short readiness summary and ask only for unresolved blockers. **Never ask the user to paste a signing key, Portal API key, or other secret into chat.** Ask only whether it exists and where the application expects it. 4. Build a TODO from the missing steps. Preserve working configuration and existing Portal resources unless the user explicitly wants replacements. @@ -99,18 +99,29 @@ The credential decides what the user proves. Nail this down before scaffolding |---|---|---| | **`proofOfHuman`** — Proof of Human (flagship) | The user is a unique person, biometrically verified at an Orb | Sybil resistance, airdrops, one-vote-per-human, gated signups. **The default if the user said "proof of human" or "verify a real human."** | | **`passport`** — Passport | The user holds a valid government passport (NFC-verified) | Higher-assurance flows where you need document-grade identity (regulated apps, age-gating, KYC-adjacent). | -| **`selfieCheckLegacy`** — Selfie Check (Beta) | A liveness selfie signal backed by a World ID 3.0 proof | Lower-assurance "is a human in front of the camera" — friction/bot deterrence without the full Orb requirement. | +| **`selfieCheck`** — Selfie Check | A liveness and facial-similarity credential backed by a World ID 4.0 proof | Medium-assurance friction and bot deterrence without the full Orb requirement. Returns a verified `sybil_score` risk signal. | -**DO NOT default to `proofOfHuman` if the user said "passport" or "verify their ID"** — that's `passport`. **DO NOT default to `proofOfHuman` if the user said "selfie" or "liveness"** — that's `selfieCheckLegacy`. When in doubt, ask one question. +**DO NOT default to `proofOfHuman` if the user said "passport" or "verify their ID"** — that's `passport`. **DO NOT default to `proofOfHuman` if the user said "selfie" or "liveness"** — that's `selfieCheck`. When in doubt, ask one question. -Other legacy presets exist (`documentLegacy`, `deviceLegacy`); reach for them only when the user asks specifically. For sign-in / session reuse across visits, use the v4 **session** flow instead of a uniqueness preset (see the integrate doc). +Other legacy presets exist (`documentLegacy`, `deviceLegacy`); reach for them only when the user asks specifically. For sign-in / session reuse across visits, use the v4 **session** flow (see `/world-id/idkit/session-proofs`). -### Selfie Check (Beta) access +### Selfie Check -Before implementing or testing Selfie Check, confirm that its feature flag is -enabled for the target app. If it is not enabled, stop and tell the user to -request access through their World contact or the documented support path. A -valid app or action does not imply Selfie Check access. +For repeated Selfie Check verification, use `IDKit.createSession` followed by +`IDKit.proveSession` with `.preset(selfieCheck())`. +Save the verified `session_id` against the application account +and require that same session on later checks; enforce per-proof replay protection. + +For a one-time uniqueness check, use the `selfieCheck` preset. Each Selfie Check +response includes a required integer `sybil_score`; forward the complete IDKit +result unchanged so the Developer Portal can verify the proof and version 2 +integrity signature before the app uses the score. + +World ID 4.0 uniqueness proofs are one-time per action for each user. Use separate +actions for separate one-time operations, and sessions for recurring checks. +Migrate existing `selfieCheckLegacy` integrations to the appropriate World ID 4.0 +flow above. See `/world-id/idkit/session-proofs` for the session lifecycle and +backend requirements. ## Phase 4 — Implement the 6 integration steps and explain the WHY @@ -118,6 +129,13 @@ The full code for each step is at [https://docs.world.org/world-id/idkit/integra **Copy this checklist into your TODO and update it as you go.** Don't move on with an unchecked step. +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 +uniqueness-nullifier storage with verified account-to-session binding and +per-proof replay protection. Test both creation and proving the saved session. + - [ ] Step 1 — Install IDKit - [ ] Step 2 — Create or reuse app + RP + action (store any newly generated signing key immediately) - [ ] Step 3 — Sign RP request in backend @@ -150,7 +168,7 @@ Do not declare the integration complete from compilation or Portal configuration - [ ] Backend verification succeeds and the exact IDKit result reaches `/api/v4/verify/{rp_id}`. - [ ] The verified nullifier is persisted. - [ ] Replaying the same nullifier is rejected by the database uniqueness constraint. -- [ ] Relevant failures—unavailable Selfie Check, invalid action/signature, or environment mismatch—produce an actionable user-facing error instead of an indefinite loading state. +- [ ] Relevant failures—replayed nullifiers, invalid action/signature, or environment mismatch—produce an actionable user-facing error instead of an indefinite loading state. - [ ] JS/React failures retain the `debugReport` and `request_id` needed for diagnosis without logging secrets. Run automated tests for the routes and persistence behavior. Clearly identify simulator, phone, or production checks that still require the user; never imply a manual proof flow ran when it did not. diff --git a/world-id/credentials/11.mdx b/world-id/credentials/11.mdx index 067ea0d..40ee9bf 100644 --- a/world-id/credentials/11.mdx +++ b/world-id/credentials/11.mdx @@ -1,5 +1,5 @@ --- -title: "Selfie Check (Beta)" +title: "Selfie Check" icon: "camera" iconType: "duotone" description: "A medium-assurance biometric credential using the device camera for liveness and facial similarity." @@ -22,14 +22,13 @@ import { CredentialHero } from "/snippets/credential-hero.jsx"; @@ -39,22 +38,19 @@ import { CredentialHero } from "/snippets/credential-hero.jsx"; | Property | Value | | --- | --- | | Issued by | [Tools for Humanity](https://www.toolsforhumanity.com) (verified issuer) | - | Status | Beta | | ID | `11` | | Validity period | 90 days (the default duration of the credential; generally the maximum recommended sybil resistance window) | ## Introduction -Selfie Check (Beta) uses the user's mobile device camera for liveness and facial +Selfie Check 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 and is considered a medium-assurance verification method. -It returns a proof of the completed check, not a numeric Sybil or uniqueness -score. -Use Selfie Check (Beta) for: +Use Selfie Check for: * **Liveness detection:** Confirm the user is a real person, not a spoof or injection attack. * **Abuse resistance:** Add friction to automated and repeated account creation. @@ -63,14 +59,33 @@ Use Selfie Check (Beta) for: 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. - - -Once enabled, anyone with World ID App can use Selfie Check. No Orb, passport or +Anyone with World ID App can use Selfie Check. No Orb, passport or other prerequisite credential is required. +## Understand the Sybil score + +Each Selfie Check response includes a versioned `sybil_score` that +can help an app assess the risk of repeated enrollment. It is a risk signal, not +a uniqueness verdict, and should be considered alongside other evidence. The +response also includes an `integrity_bundle` that lets the Developer Portal +verify it came from an authentic World ID App. + +## Choose your integration + +Use **session proofs** if users need to complete Selfie Check more than once—for +example, when returning to your app or confirming a sensitive action. Create a +session on their first successful verification, then prove that same session on +subsequent checks. + +Use a **uniqueness request** when your app needs to allow each user to complete a +particular action once, such as claiming a reward. The one-time nullifier for that +action cannot serve as a reusable verification flow. Selfie Check remains a +medium-assurance signal; neither flow provides a strict one-person-one-account +guarantee. + +- [Integrate with sessions](/world-id/idkit/session-proofs) — recommended for returning-user checks. +- [Integrate a one-time check](/world-id/idkit/integrate) — use a uniqueness request. + ## How it works Use IDKit to integrate Selfie Check into your application. diff --git a/world-id/idkit/credentials.mdx b/world-id/idkit/credentials.mdx index 7db3ccd..17d92e9 100644 --- a/world-id/idkit/credentials.mdx +++ b/world-id/idkit/credentials.mdx @@ -14,7 +14,7 @@ A [Credential](https://docs.rs/world-id-primitives/latest/world_id_primitives/cr | --- | --- | --- | | Proof of Human | The user is a unique human, backed by anonymous biometric verification by the Orb. | `proofOfHuman` | | Passport | The user holds a verified NFC passport credential. | `passport` | -| Selfie Check (Beta) | A medium-assurance biometric credential using the device camera for liveness and facial similarity. | `selfieCheckLegacy` | +| Selfie Check | A medium-assurance biometric credential using the device camera for liveness and facial similarity. | `selfieCheck` | | Identity Check | An attestation that a document-backed property about the user matches your requested attributes. | `identityCheck` with attributes like `minimum_age`, `nationality`, or `document_type`. | You can also add a liveness check to any preset with `require_user_presence`. @@ -25,7 +25,7 @@ You can also add a liveness check to any preset with `require_user_presence`. # SDK presets -Preset helpers cover common credential requests: `proofOfHuman`, `passport`, `selfieCheckLegacy`, `identityCheck`, and the legacy presets. +Preset helpers cover common credential requests: `proofOfHuman`, `passport`, `selfieCheck`, `identityCheck`, and the legacy presets. The snippets below assume `rp_context` was already generated and signed by your backend. See [Integrate IDKit](/world-id/idkit/integrate) for the full RP-signing flow. @@ -103,52 +103,34 @@ const preset = passport({ signal: "user-123" }); ``` -## Selfie Check (Beta) +## Selfie Check - - [Request access](mailto:developers@toolsforhumanity.com) to enable Selfie Check - (Beta) for your app. - - -Once enabled, use `selfieCheckLegacy()` to request Selfie Check. The preset -currently uses World ID 3.0; World ID 4.0 support is not yet available. +Use `selfieCheck()` 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. Anyone with World ID App can complete the flow—no Orb or document credential is -required. Forward the complete IDKit result to the -[verification endpoint](/api-reference/developer-portal/verify). - - -```typescript title="JavaScript" -import { IDKit, selfieCheckLegacy } from "@worldcoin/idkit-core"; +required. -const preset = selfieCheckLegacy({ signal: "user-123" }); +```typescript +import { IDKit, selfieCheck } from "@worldcoin/idkit-core"; -const request = await IDKit.request({ +const request = await IDKit.createSession({ app_id: "app_xxxxx", - action: "my-action", rp_context, -}).preset(preset); +}).preset(selfieCheck()); ``` -```tsx title="React" -import { IDKitRequestWidget, selfieCheckLegacy } from "@worldcoin/idkit"; - -const preset = selfieCheckLegacy({ signal: "user-123" }); +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 +succeeds. - { /* ... */ }} -/>; -``` - +For a one-time check, use `IDKit.request(...).preset(selfieCheck())` with an +`action` and `allow_legacy_proofs: false`. Each user can complete that action once; +see the [integration guide](/world-id/idkit/integrate). -To test your integration end-to-end, see [Testing Selfie Check in Sandbox](/world-id/sandbox/testing-selfie-check). +If you use `selfieCheckLegacy`, migrate to `selfieCheck` for World ID 4.0. ## Identity Check (Preview) @@ -280,7 +262,7 @@ These presets only return World ID 3.0 proofs. Use them for existing integration deviceLegacy - Deprecated. Keep deviceLegacy only for existing Device integrations. For new integrations, use Selfie Check (Beta). + Deprecated. Keep deviceLegacy only for existing Device integrations. For new integrations, use Selfie Check. diff --git a/world-id/idkit/integrate.mdx b/world-id/idkit/integrate.mdx index a425584..1b98939 100644 --- a/world-id/idkit/integrate.mdx +++ b/world-id/idkit/integrate.mdx @@ -16,7 +16,7 @@ Use the React widget for drop-in integration, or the JS, Swift and Kotlin SDKs f ## How it works -Send a **proof request** through IDKit, challenging the user to prove something about themselves — such as uniqueness, document possession or liveness — based on their [credentials](/world-id/overview#credentials). The user's World ID App generates a zero-knowledge proof without revealing personal data. Your backend then verifies the proof and stores a **nullifier** (a per-app, per-action identifier) to prevent the same person from verifying twice. +Use IDKit to request a proof and verify it on your backend: follow this guide for one-time checks, or use [session proofs](/world-id/idkit/session-proofs) for returning users.
IDKit integration flow: your app sends a proof request to World App, receives a ZK proof, forwards it to your backend, and the backend verifies it with the World ID Developer Portal @@ -336,14 +336,18 @@ export async function POST(request: Request): Promise { return NextResponse.json({ error: "Verification failed" }, { status: 400 }); } - // Proof is valid — now store the nullifier (see Step 6) + // Uniqueness: store the nullifier (Step 6). + // Sessions: validate and store the session result (see the session guide). return NextResponse.json({ success: true }); } ``` # Step 6: Store the nullifier -Every World ID proof contains a nullifier — a value derived from the user's World ID, your app, and the action. The same person verifying the same action always produces the same nullifier, but different apps or actions produce different ones, making nullifiers unlinkable across apps. +This step applies to uniqueness requests. For session proofs, follow the +[session guide](/world-id/idkit/session-proofs). + +Every uniqueness proof contains a nullifier — a value derived from the user's World ID, your app, and the action. The same person verifying the same action always produces the same nullifier, but different apps or actions produce different ones, making nullifiers unlinkable across apps. The Developer Portal confirms the proof is **cryptographically valid**, but your backend must check that the nullifier hasn't been used before. Otherwise, the same person could verify multiple times for the same action. diff --git a/world-id/idkit/javascript.mdx b/world-id/idkit/javascript.mdx index 83ef949..03d8ce6 100644 --- a/world-id/idkit/javascript.mdx +++ b/world-id/idkit/javascript.mdx @@ -28,7 +28,8 @@ yarn add @worldcoin/idkit-core - `IDKit.request(config)` for uniqueness proofs - `IDKit.requestWithInviteCode(config)` for invite-code mode -- `orbLegacy`, `secureDocumentLegacy`, `documentLegacy`, `selfieCheckLegacy` for presets +- `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(...)`. @@ -129,14 +130,14 @@ if (!completion.success) { Use `IDKit.requestWithInviteCode(config)` to open a landing page that displays both an invite code and a QR code. Validation, the returned `Status` shape, and the poll loop are identical to `IDKit.request`. See [Invite-code mode](/world-id/idkit/verification-flows#with-invite-code-mode) for when to use it. ```ts -import { IDKit, selfieCheckLegacy } from "@worldcoin/idkit-core"; +import { IDKit, proofOfHuman } from "@worldcoin/idkit-core"; const request = await IDKit.requestWithInviteCode({ app_id: "app_xxxxx", action: "my-action", rp_context, allow_legacy_proofs: true, -}).preset(selfieCheckLegacy({ signal: "user-123" })); +}).preset(proofOfHuman({ signal: "user-123" })); const connectorURI = request.connectorURI; // URL with &c=&a= const expiresAt = request.expiresAt; // Unix seconds @@ -174,7 +175,7 @@ const request = await IDKit.requestWithInviteCode({ action: "my-action", rp_context, allow_legacy_proofs: true, -}).preset(selfieCheckLegacy({ signal: "user-123" })); +}).preset(proofOfHuman({ signal: "user-123" })); const connectorURI = request.connectorURI; // display to user (URL with code embedded) const expiresAt = request.expiresAt; // drive a countdown diff --git a/world-id/idkit/kotlin.mdx b/world-id/idkit/kotlin.mdx index b0f8fae..bee812e 100644 --- a/world-id/idkit/kotlin.mdx +++ b/world-id/idkit/kotlin.mdx @@ -80,6 +80,16 @@ import com.worldcoin.idkit.orbLegacy val request = IDKit.request(config).preset(orbLegacy(signal = "user-123")) ``` +For a one-time Selfie Check, use `selfieCheck(signal)`. It requests World ID 4.0 and always +disables legacy fallback. See [Configure Credentials](/world-id/idkit/credentials#selfie-check) +for response verification and repeated-check guidance. + +```kotlin +import com.worldcoin.idkit.selfieCheck + +val request = IDKit.request(config).preset(selfieCheck(signal = "user-123")) +``` + ## Polling patterns - `pollStatusOnce()` for manual loops diff --git a/world-id/idkit/mini-apps.mdx b/world-id/idkit/mini-apps.mdx index 9420b03..b8166c3 100644 --- a/world-id/idkit/mini-apps.mdx +++ b/world-id/idkit/mini-apps.mdx @@ -37,9 +37,12 @@ The Mini-App-specific details: | Goal | IDKit preset | | --- | --- | | Strong sybil resistance or one-human-one-action checks | `proofOfHuman` | -| Lower-friction liveness or bot deterrence | `selfieCheckLegacy` | +| Lower-friction liveness or bot deterrence | `selfieCheck` | | Passport-backed checks | `passport` | +For repeated Selfie Check verification of returning users, use +[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. ## Example diff --git a/world-id/idkit/react.mdx b/world-id/idkit/react.mdx index ff2c1f3..331a54b 100644 --- a/world-id/idkit/react.mdx +++ b/world-id/idkit/react.mdx @@ -122,7 +122,7 @@ Hook result fields: For invite-code flows, use `IDKitInviteCodeRequestWidget` (controlled) or `useIDKitInviteCodeRequest` (headless). Config matches `IDKitRequestWidget` / `useIDKitRequest` — invite-code mode adds no new required fields. See [Invite-code mode](/world-id/idkit/verification-flows#with-invite-code-mode) for when to use it. ```tsx -import { IDKitInviteCodeRequestWidget, selfieCheckLegacy } from "@worldcoin/idkit"; +import { IDKitInviteCodeRequestWidget, proofOfHuman } from "@worldcoin/idkit"; { /* ... */ }} onSuccess={() => { /* ... */ }} />; @@ -172,7 +172,7 @@ import { IDKitRequestWidget, orbLegacy } from "@worldcoin/idkit"; ```tsx // After — invite-code widget -import { IDKitInviteCodeRequestWidget, selfieCheckLegacy } from "@worldcoin/idkit"; +import { IDKitInviteCodeRequestWidget, proofOfHuman } from "@worldcoin/idkit"; ; diff --git a/world-id/idkit/session-proofs.mdx b/world-id/idkit/session-proofs.mdx new file mode 100644 index 0000000..a8d9404 --- /dev/null +++ b/world-id/idkit/session-proofs.mdx @@ -0,0 +1,93 @@ +--- +title: "Session proofs" +description: "Verify returning users with World ID, including repeated Selfie Check verification." +"og:image": "https://docs.world.org/images/docs/docs-meta.png" +"twitter:image": "https://docs.world.org/images/docs/docs-meta.png" +--- + +Use session proofs when the same user needs to verify again, such as when returning +to your app or confirming a sensitive action. This is the recommended flow for +[Selfie Check](/world-id/credentials/11) integrations that need repeated verification. + +A uniqueness request allows each user to complete a particular action once. A +session lets the user prove continuity across multiple checks: create it once, +then prove the saved session on subsequent checks. + +| Value | Purpose | Backend responsibility | +| --- | --- | --- | +| `session_id` | Identifies the session across checks. | Associate the verified value with your application account and require it on later checks. | +| `session_nullifier` | Per-proof replay protection, returned as `[nullifier, action]`. | Reject reuse of an already accepted proof; do not use this value as the account identifier. | + +A World ID session is not your application's login cookie or access token. Your +backend decides what a successful verification authorizes. + +## Before you start + +Complete the [installation and Portal setup](/world-id/idkit/integrate#step-1-install-idkit) +and use the same [backend verification endpoint](/world-id/idkit/integrate#step-5-verify-the-proof-in-your-backend) +as other IDKit flows. This guide covers the session-specific changes. + +Generate fresh [RP signatures](/world-id/idkit/signatures) for session creation and +each subsequent check. Call `signRequest({ signingKeyHex })` without an `action`; +session requests do not take an action or support legacy proofs. + +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. + +## Create a session + +```typescript +import { IDKit, selfieCheck } from "@worldcoin/idkit-core"; + +const request = await IDKit.createSession({ + app_id, + rp_context, + environment: "production", +}).preset(selfieCheck()); + +// Display request.connectorURI as a link or QR code, then wait for the user. +const completion = await request.pollUntilCompletion({ timeout: 120_000 }); +if (!completion.success) throw new Error(completion.error); + +// Send completion.result unchanged to your backend for verification. +// Save its session_id against the account only after verification succeeds. +``` + +The `selfieCheck()` preset 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`. +Associate it with the account completing enrollment. Treat linking or replacing +an account's session as an account-security operation; do not silently replace +the saved value whenever the client submits a new session. + +## Verify a returning user + +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"; + +const request = await IDKit.proveSession(savedSessionId, { + app_id, + rp_context, + environment: "production", +}).preset(selfieCheck()); + +const completion = await request.pollUntilCompletion({ timeout: 120_000 }); +if (!completion.success) throw new Error(completion.error); + +// Send completion.result unchanged to your backend. +// Verify it and require session_id to match the account's saved session. +``` + +`savedSessionId` is the opaque `session_...` string returned during creation. +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 +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. diff --git a/world-id/idkit/swift.mdx b/world-id/idkit/swift.mdx index 95585b5..9053c1b 100644 --- a/world-id/idkit/swift.mdx +++ b/world-id/idkit/swift.mdx @@ -57,6 +57,16 @@ let request = try IDKit.request(config: config).preset( ) ``` +For a one-time Selfie Check, use `selfieCheck(signal:)`. It requests World ID 4.0 and always +disables legacy fallback. See [Configure Credentials](/world-id/idkit/credentials#selfie-check) +for response verification and repeated-check guidance. + +```swift +let request = try IDKit.request(config: config).preset( + selfieCheck(signal: "user-123") +) +``` + ## Polling API - `pollStatusOnce() async -> IDKitStatus` @@ -82,7 +92,7 @@ Use `presetWithInviteCode(_:)` on the builder to return an `IDKitInviteCodeReque ```swift let request = try IDKit.request(config: config) - .presetWithInviteCode(selfieCheckLegacy(signal: "user-123")) + .presetWithInviteCode(proofOfHuman(signal: "user-123")) let connectorURL = request.connectorURL // URL with &c=&a= let expiresAt = request.expiresAt // Date @@ -103,7 +113,7 @@ let completion = await request.pollUntilCompletion() ```swift // After — invite-code mode let request = try IDKit.request(config: config) - .presetWithInviteCode(selfieCheckLegacy(signal: "user-123")) + .presetWithInviteCode(proofOfHuman(signal: "user-123")) let connectorURL = request.connectorURL // display to user (URL with code embedded) let expiresAt = request.expiresAt // drive a countdown diff --git a/world-id/idkit/verification-flows.mdx b/world-id/idkit/verification-flows.mdx index a1467b6..8e20009 100644 --- a/world-id/idkit/verification-flows.mdx +++ b/world-id/idkit/verification-flows.mdx @@ -130,4 +130,4 @@ sequenceDiagram **Integrate** -Setup is identical to the [standard integration](/world-id/idkit/integrate) — only the request call changes. Only the `selfieCheckLegacy` preset is supported for Selfie Check (Beta) today. It returns World ID 3.0 proofs; Selfie Check with World ID 4.0 is not available yet. For code samples and migration guides, see the per-SDK sections: [JavaScript](/world-id/idkit/javascript#invite-code-mode), [React](/world-id/idkit/react#invite-code-mode), [Swift](/world-id/idkit/swift#invite-code-mode). +Setup is identical to the [standard integration](/world-id/idkit/integrate) — only the request call changes. Choose the appropriate preset in [Configure Credentials](/world-id/idkit/credentials). For code samples and migration guides, see the per-SDK sections: [JavaScript](/world-id/idkit/javascript#invite-code-mode), [React](/world-id/idkit/react#invite-code-mode), [Swift](/world-id/idkit/swift#invite-code-mode). diff --git a/world-id/overview.mdx b/world-id/overview.mdx index 248957f..89abe2b 100644 --- a/world-id/overview.mdx +++ b/world-id/overview.mdx @@ -89,8 +89,7 @@ Through credentials like Proof of Human, Document, and Selfie Check, World ID ex Selfie Check credential card - {/* Mintlify wraps heading children in its own span, so the badge alignment lives on this inner span, not on the h3. */} -

Selfie Check Beta

+

Selfie Check

Low-friction liveness and uniqueness signal from a selfie flow. Best for sign-up and bot defense where speed matters most.

@@ -100,7 +99,7 @@ Through credentials like Proof of Human, Document, and Selfie Check, World ID ex - [Proof of Human](/world-id/credentials/1) — Highest-assurance uniqueness signal from Orb verification. Best for one-person-one-action flows and strong Sybil resistance. - [Document](/world-id/credentials/9303) — Proves possession of a unique government document through NFC checks. Useful for proof of age and document-backed access flows. - - [Selfie Check (Beta)](/world-id/credentials/11) — Low-friction liveness and uniqueness signal from a selfie flow. Best for sign-up and bot defense where speed matters most. + - [Selfie Check](/world-id/credentials/11) — Low-friction liveness and uniqueness signal from a selfie flow. Best for sign-up and bot defense where speed matters most. ## Start building diff --git a/world-id/sandbox/testing-selfie-check.mdx b/world-id/sandbox/testing-selfie-check.mdx index 8c45d71..c35ef71 100644 --- a/world-id/sandbox/testing-selfie-check.mdx +++ b/world-id/sandbox/testing-selfie-check.mdx @@ -1,21 +1,16 @@ --- -title: "Testing Selfie Check (Beta) in Sandbox" -description: "Coverage, critical user journeys, and known limitations for testing your Selfie Check (Beta) integration in Sandbox." +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 (Beta)](/world-id/credentials/11) relying-party +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. - - Selfie Check (Beta) must be enabled for your app before you can test it. To - enable the feature flag, request access through your World point of contact. - - 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.