Start Here
- Register or upgrade your app in the Developer Portal.
- Upgrade to IDKit 4.x (see below).
- Choose a migration path below based on your app’s behavior.
Uniqueness vs Session Proofs (3.0 to 4.0)
World ID 4.0 has two proof types:- Uniqueness proofs for one-time checks.
- Session proofs for returning-user continuity (new in 4.0).
session_id is the stable link across requests.
Rule of thumb: use
nullifier for one-time uniqueness and session_id for continuity.
Upgrading to IDKit 4.x
Adopting World ID 4.0 requires upgrading to IDKit 4.x, which introduces major breaking changes to support the new protocol. What changed:- RP context is required: Requests now require
rp_context(rp_id,nonce,created_at,expires_at,signature). - IDKit response changed: No longer reshape the payload or compute
signal_hashfor the verify endpoint. - Backend verification endpoint changed: Use
POST /api/v4/verify/{rp_id}. @worldcoin/idkit-standaloneis discontinued. Use@worldcoin/idkit-corefor vanilla JS/browser.
Migration Timeline (Phase Dates)
Use these dates as the default migration timeline:- 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
CD later.
Migration Path
Choose a migration path based on how you previously used World ID in your application.One time actions
These apps have a single long-running action. Examples: A stamp for every verified human in the world. A token given to every human in the world once.Important:
genesis_issued_at is when the user originally got their
credential (for example, went to an Orb), not when they upgraded their
authenticator to v4. A user who was Orb-verified in 2023 and upgrades to v4
in 2025 still has genesis_issued_at from 2023.Migration Flow Diagram
This diagram shows the three-phase migration process: preparation, gradual transition, and v3 cut-off. Summary: During Phase 2, both v3 and v4 proofs are accepted. Phase 3 enforces v4-only.Step-by-step Migration Details
- Update SDKs and Contracts: Upgrade SDKs, contracts, and API calls to enable baseline support for the upgraded protocol. This is backwards compatible.
- Register in Developer Portal: Generate your new RP registration and relevant actions for the v4 protocol in the Developer Portal.
- For long-running actions:
- Decide a transition date (
TD) to start accepting v4 proofs. Specify a minimumgenesis_issued_at = TDtimestamp in the IDKit request withallow_legacy_proofs: trueas a temporary compatibility mode. Only users who get their Orb credential (or document credentials) from this point forward can generate v4 proofs. Users who have not upgraded their World ID can still issue v3 proofs during this window. Track both nullifiers. - At a future cut-off date (
CD > TD), switch the IDKit request toallow_legacy_proofs: falseto stop accepting v3 proofs and accept only v4 proofs.
- Decide a transition date (
- For limited-time actions (for example, recurring grant drops): Make the transition at the action level. Short-running actions have a simpler migration path.
Example Code
Old Contract - Disable minting here:Mint.sol
Mintv4.sol
Short Term Recurring Actions
These apps create multiple one-time actions. These actions are short lived. Example: A daily voting app where each vote requires a fresh proof of unique human. 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. Summary: During Phase 2, only accept v4 proofs for new actions.Recurring Verifications and New Credential Checks
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, 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 Flow Diagram
This diagram shows how Session Proofs provide a stable identifier across multiple verifications. Summary: Session IDs provide continuity across verifications, replacing nullifiers as the stable identifier.Creating a session
Proving a session
New Apps
Apps launched after v4 is fully released will not need to migrate.Further Migration Details
- Recovery applies to users in the v4 protocol. Users with pre-v4 credentials
may receive a new credential based on issuer policy, while
genesis_issued_atstill reflects original issuance date.