Introduction

Integration guide

This guide will walk you through everything you need to get started with World ID or Sign in with World ID!

1. Sign in to the Developer Portal. You will need a World ID-compatible wallet (such as the World App) and a Device- or Orb-Verified World ID to sign in.

   While adding your email is optional, adding it is encouraged. This will allow you to maintain access to your Developer Portal account should you lose your World ID.

2. Decide whether you're going to use Sign in with World ID or Incognito Actions. Here's a helpful guide:

   Sign in with World IDIncognito Actions

   Sign in with World ID

   Sign in with World ID is built to bring the privacy benefits of World ID to a broad range of apps as easily as possible. It is a simple, drop-in authentication mechanism that works with any OIDC-compatible authentication engine.

   ✅ When to use Sign in with World ID:

   • You want to know that an account belongs to a real person, and each real person only has one account.
   • You already use Auth0, NextAuth, or a similar authentication engine in your app.
   • You want to allow users to preserve their privacy, or even stay completely anonymous.

   🚫 When not to use Sign in with World ID:

   • Your app has an on-chain component (e.g. a smart contract).
   • You want a user to be able to have multiple accounts and keep them separate.
   • You want to verify a user is doing a specific action only once.

3. Create and configure your first app.

   • Name your app something recognizable. It will be displayed to users when they are asked to Verify with World ID.
   • Select the environment to use: Staging or Production.
     • Use Staging apps for testing and development. You must use the Worldcoin Simulator to verify actions.
     • Use Production apps for production. You must use the World App to verify actions.
   • Select whether you want this action to be cloud-based or on-chain. Cloud-based actions are verified with our Cloud API, while on-chain actions are verified by our smart contracts on the blockchain.

     If you want to use Sign in with World ID, ensure you select Cloud-based.

4. Note your App ID (also called the Client ID). It looks something like app_GBkZ1KlVUdFTjeMXskrX. For Sign in with World ID, you should also note your Client Secret, which is found alongside the Client ID in the Sign In tab.

5. Follow our guides specific to your use case:

   Sign in with World IDCloud Incognito ActionsOn-Chain Incognito Actions

   Follow the Auth0 Integration installation instructions to add Sign in with World ID to your Auth0 Tenant using the Client ID and Client Secret found in the Developer Portal.

   If your app hasn't yet integrated Auth0, you can use any of their various SDK libraries to get started. This allows using Sign in with World ID on a very broad range of platforms, including web, mobile, and desktop apps.

6. Test your integration with the Worldcoin Simulator and a Staging App ID.

   • You can use the Simulator as a web app on either desktop or mobile.
   • Select which identity to use in the Simulator. All identities are already Device- and Orb-verified, and you can choose which credentials to use after scanning the QR code.
     • You can always change identities by tapping the identity icon in the top-left of the simulator.
     • Add more identities by tapping the "+" in the bottom-right.
     • Only Orb credentials are supported on-chain.
   • To begin the World ID verification, tap "Scan QR or Paste data."
     • On mobile, you can scan the QR code with the camera, just as you would in World App.
     • On desktop, you can click the QR code in IDKit to copy the data, then click "Manual Input" to paste the data from the QR code into the Simulator.
   • Select which credential(s) to use for this verification. If multiple credentials are selected, the highest-strength credential will be used.
   • Tap "Verify with World ID" to complete the verification!