ID Kit

Integrating on Web (React)

For react integrations, we support 2 paths:

Widget: A plug-and-play widget that handles UI/State management for you. Find an example here
Session API: A react hook that gives you total control of the user journey and UI/State management. Find an example here.

Install

npm i @worldcoin/idkit

First, add the IDKitWidget component to your site. The values for the app_id and action props were obtained from the Developer Portal in Getting Started. We'll define the handleVerify and onSuccess callbacks next.

/verify.tsx

'use client' // for Next.js app router
import { IDKitWidget, VerificationLevel, ISuccessResult } from '@worldcoin/idkit'

// ...
;<IDKitWidget
	app_id="your app id" // obtained from the Developer Portal
	action="your action id" // obtained from the Developer Portal
	onSuccess={onSuccess} // callback when the modal is closed
	handleVerify={handleVerify} // callback when the proof is received
	verification_level={VerificationLevel.Orb}
>
	{({ open }) => (
		// This is the button that will open the IDKit modal
		<button onClick={open}>Verify with World ID</button>
	)}
</IDKitWidget>

handleVerify

The handleVerify callback is called when the user's proof is received. This will send the proof to your backend for verification:

/verify.tsx

const handleVerify = async (proof: ISuccessResult) => {
	const res = await fetch('/api/verify', {
		// route to your backend will depend on implementation
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
		},
		body: JSON.stringify(proof),
	})
	if (!res.ok) {
		throw new Error('Verification failed.') // IDKit will display the error message to the user in the modal
	}
}

Verifying the proof

The handleVerify callback sends the proof to your backend for verification. In the backend handler should verify the proof with the Developer Portal API:

The call to the Developer Portal API must be made server-side to avoid man in the middle attacks.

/api/verify.ts

import { type IVerifyResponse, verifyCloudProof } from '@worldcoin/idkit-core'

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
	const proof = req.body
	const app_id = process.env.APP_ID
	const action = process.env.ACTION_ID
	const verifyRes = (await verifyCloudProof(proof, app_id, action)) as IVerifyResponse

	if (verifyRes.success) {
		// This is where you should perform backend actions if the verification succeeds
		// Such as, setting a user as "verified" in a database
		res.status(200).send(verifyRes)
	} else {
		// This is where you should handle errors from the World ID /verify endpoint.
		// Usually these errors are due to a user having already verified.
		res.status(400).send(verifyRes)
	}
}

If you want to verify the proof onchain read more about it here.

onSuccess

The onSuccess callback is called when the user closes the modal. This is where you can perform any necessary actions, such as redirecting the user to a new page.

/verify.tsx

const onSuccess = () => {
	// This is where you should perform any actions after the modal is closed
	// Such as redirecting the user to a new page
	window.location.href = '/success'
}

Session Hook

First, setup the session hook with your configuration:

/verify.tsx

const { status, sessionURI, result, errorCode } = useSession({
	app_id: 'your app id',
	action: 'your action id',
})

After that you need to handle the following possible statuses:

WaitingForConnection: Display the sessionURI to the user eg. with a QR code
Confirmed: Session ended successfully, now you must verify the result proof in your backend.
Failed: Session failed, check errorCode