Technical Reference
IDKit
IDKit is open source and accepts contributions! Head over to GitHub and submit a pull request.
There are three packages available in the IDKit Monorepo: @worldcoin/idkit
, @worldcoin/idkit-standalone
, and @worldcoin/idkit-core
. The @worldcoin/idkit
package is the main package that should be used with the React JS framework. The @worldcoin/idkit-standalone
package is a standalone package that can be used in vanilla JavaScript applications. The @worldcoin/idkit-core
package is a core functionality package that is used by the other two packages, and should be used only when creating a new IDKit package.
IDKit (React)
The @worldcoin/idkit
package is the main package that should be used with the React framework or any other framework that supports React components, such as Next.JS.
Components
IDKitWidget
The IDKitWidget
component is the main component that renders the World ID widget. It should be mounted in your React app and passed the relevant parameters. Accepts a function as a child that receives an open
function to open the widget.
import { IDKitWidget } from '@worldcoin/idkit'
<IDKitWidget
app_id="app_GBkZ1KlVUdFTjeMXKlVUdFT" // obtained from the Developer Portal
action="vote_1" // this is your action name from the Developer Portal
signal="user_value" // any arbitrary value the user is committing to, e.g. a vote
onSuccess={onSuccess}
verification_level="device" // minimum verification level accepted, defaults to "orb"
>
{({ open }) => <button onClick={open}>Verify with World ID</button>}
</IDKitWidget>
Parameters
The following parameters can be passed as props to the IDKitWidget
component:
- Name
app_id
- Type
- string
- Required
- REQUIRED
- Description
Unique identifier for the app verifying the action. This should be the App ID obtained from the Developer Portal.
- Name
action
- Type
- string
- Required
- REQUIRED
- Description
Identifier for the action the user is performing. This should be the action name set in the Developer Portal.
- Name
onSuccess
- Type
- function(ISuccessResult)
- Required
- REQUIRED
- Description
Function to trigger when verification is successful and the modal is closed. Should receive a single parameter of type
ISuccessResult
which contains the proof details.
- Name
handleVerify
- Type
- function(ISuccessResult)
- Description
Called after the proof is returned from the user's identity wallet (e.g. World App), but before showing the success screen. Should receive a single parameter of type
ISuccessResult
which contains the proof details. Throwing an error in this screen will show the user a custom error.handleVerify
should be used for API proof verifications to create the best user experience. This will show a pending state while the proof is verified and present any errors thrown in a user-readable fashion.
- Name
onError
- Type
- function(IErrorState)
- Description
Called when IDKit is closed after an error. Should receive a single parameter of type
IErrorState
which contains the error details.
- Name
verification_level
- Type
- string:
orb
- Description
The minimum verification level accepted. Can be
orb
ordevice
. Defaults toorb
. TypeScript apps can use theVerificationLevel
enum.
- Name
signal
- Type
- string:
""
- Description
The signal to be included in the zero-knowledge proof. Typically used for on-chain actions, read more in the On-chain section.
- Name
bridge_url
- Type
- string:
"https://bridge.worldcoin.org"
- Description
The URL of the Wallet Bridge to use for establishing a connection between IDKit and the user's World ID Wallet. Defaults to the bridge service hosted by Worldcoin. Only change this if you are running your own bridge service. Read more in Protocol Internals.
World App will temporarily prevent users from connecting to a Wallet Bridge that is not hosted by Worldcoin or Tools for Humanity while security reviews are ongoing, so we recommend using the default value by leaving thebridge_url
parameter undefined.
- Name
autoClose
- Type
- boolean:
true
- Description
Whether to automatically close the widget after completion. Defaults to
true
.
- Name
advanced
- Type
- JSON
- Description
A JSON object containing advanced configuration options that may be unstable or subject to change. See Advanced Configuration for more details.
Hooks
useIDKit
The useIDKit
hook allows you to programmatically open the IDKit widget without mounting any buttons on screen. Note that you still need to mount the component for this to work.
import { IDKitWidget, useIDKit } from '@worldcoin/idkit'
const { open, setOpen } = useIDKit()
useEffect(() => {
setOpen(true)
}, [])
return (
<div>
<IDKitWidget app_id="..." action="..." />
</div>
)
Functions
verifyCloudProof
The verifyCloudProof
function is used to verify a proof returned from the user's identity wallet (e.g. World App) against the Developer Portal API. This function is useful for verifying proofs on the server side.
- Name
proof
- Type
- ISuccessResult
- Required
- REQUIRED
- Description
The proof object returned from IDKit.
- Name
app_id
- Type
- app_${string}
- Required
- REQUIRED
- Description
The app_id obtained from the Developer Portal.
- Name
action
- Type
- string
- Required
- REQUIRED
- Description
The action id from the Developer Portal.
- Name
signal
- Type
- string:
""
- Description
The signal as input to IDKit.
- Name
endpoint
- Type
- URL | string:
https://developer.worldcoin.org/api/v2/verify/${app_id}
- Description
The endpoint to send the proof to for verification. Defaults to the Worldcoin Developer Portal.
verifyCloudProof
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
const { proof, action, signal } = req.body
const app_id = process.env.APP_ID
const response = (await verifyCloudProof(proof, app_id, action, signal)) as IVerifyResponse
res.status(response.success ? 200 : 400).json(response)
}
Types
ISuccessResult
- Name
merkle_root
- Type
- string
- Description
This is the hash pointer to the root of the Merkle tree that proves membership of the user's identity in the list of identities verified by the Orb. ABI encoded.
- Name
nullifier_hash
- Type
- string
- Description
Essentially the user's unique identifier for your app (and specific action if using Incognito Actions). ABI encoded.
- Name
proof
- Type
- string
- Description
The Zero-knowledge proof of the verification. ABI encoded.
- Name
verification_level
- Type
- "orb" | "device"
- Description
Either
orb
ordevice
. Returns the verification level used to generate the proof.
- Name
credential_type
- Type
- "orb" | "device"
- Deprecated
- DEPRECATED
- Description
Either
orb
ordevice
. Will always return the strongest credential with which a user has been verified.This property is deprecated and will be removed in a future release. Useverification_level
instead.
ISuccessResult
{
"merkle_root": "0x1f38b57f3bdf96f05ea62fa68814871bf0ca8ce4dbe073d8497d5a6b0a53e5e0",
"nullifier_hash": "0x0339861e70a9bdb6b01a88c7534a3332db915d3d06511b79a5724221a6958fbe",
"proof": "0x063942fd7ea1616f17787d2e3374c1826ebcd2d41d2394...",
"verification_level": "orb"
}
IErrorState
- Name
code
- Type
- string
- Description
- The error code.
- Name
detail
- Type
- string
- Description
A human-readable description of the error.
IErrorState
{
"code": "already_signed",
"detail": "User has previously signed and submitted proof for this action."
}
IVerifyResult
- Name
success
- Type
- boolean
- Description
- If the proof verification succeeded.
- Name
code
- Type
- string | undefined
- Description
- The error code.
- Name
detail
- Type
- string | undefined
- Description
A human-readable description of the error.
- Name
attribute
- Type
- string | null | undefined
- Description
- The attribute causing the error.
IVerifyResult
{
"success": false,
"code": "invalid_proof",
"detail": "The provided proof is invalid and it cannot be verified. Please check all inputs and try again.",
"attribute": null,
}
Error Handling
An error in IDKit will generally be returned as the input to the onError
callback. IDKit will display an error to the user and call the onError
callback with an IErrorState
object when the modal is closed.
IDKit Standalone
The @worldcoin/idkit-standalone
package is intended for vanilla JS applications. It is a standalone package that acts as a wrapper around the @worldcoin/idkit
package.
Methods
The .init()
and .update()
methods take the same parameters as the React package's IDKitWidget component. See above for more details.
.init()
The .init()
method is the main initialization method used for vanilla JS apps. It should be called to start up IDKit and configure the widget.
import { IDKit } from '@worldcoin/idkit-standalone'
const onSuccess = (result) => {
// handle success
}
IDKit.init({
app_id: 'app_lshSNnaJfdt6Sohu6YAA',
action: 'my_action',
onSuccess: onSuccess,
})
.update()
The .update()
method reinitializes the widget with new parameters. It can only be called after the .init()
method.
IDKit.update({
app_id: 'app_lshSNnaJfdt6Sohu6YAA',
action: 'my_new_action',
onSuccess: onSuccess,
})
.open()
The .open()
method is used to open the widget. It can only be called after the .init()
method, typically in response to a button click.
This method returns a Promise object that will resolve when the onSuccess
callback is called, or reject when the onError
callback is called.
IDKit.open()
Advanced configuration
This section outlines advanced configuration options that may be unstable or subject to change. These options are passed as a JSON object to the advanced
prop of the IDKitWidget
component.
Self-Hosted Applications
Self-hosted applications bypass the Worldcoin Developer Portal entirely. The proof returned can not be verified by the Developer Portal API. Instead, you must verify the proof on-chain or with a custom prover service.
When using self-hosted mode, no app_id
is required, and any value passed to IDKit will be ignored. The action
you set must have sufficient uniqueness to avoid collisions with other applications. We recommend using a prefix that includes your application name, e.g. your_app_name_vote_1
.
import { IDKitWidget } from '@worldcoin/idkit'
<IDKitWidget
// no app_id is set for self-hosted applications
action="your_app_name_vote_1" // this is your action, set to whatever you'd like
signal="user_value"
onSuccess={onSuccess}
verification_level="orb" // only orb verifications are supported for self-hosted applications
advanced={
self_hosted, // enable the self-hosted mode
}
>
{({ open }) => <button onClick={open}>Verify with World ID</button>}
</IDKitWidget>