API Reference

The Worldcoin Developer Portal offers an API to enable easy verification of World IDs and relevant credentials.

Base URL

https://developer.worldcoin.org

All requests to the Developer Portal API must include a Content-Type: application/json header, a User-Agent header, and a valid JSON body.

Verify Proof

method

POST

https://developer.worldcoin.org/api/v2/verify/{app_id}

Enables you to verify a World ID proof for a Cloud action. To ensure sybil-resistance, by default, a single person can only verify once for every action. The number of allowed verifications for a single user can be configured in the Developer Portal.

This endpoint is now on version 2. The previous version at /api/v1/verify/{app_id} will be unavailable after June 30, 2024.

Request Body

nullifier_hash

string

required

The unique user identifier (called the nullifier hash in the ZKP), as provided by IDKit. See IDKit response for details.

proof

string

required

The zero-knowledge proof, as provided by IDKit. See IDKit response for details.

merkle_root

string

required

Part of the ZKP, the hash of the Merkle root that proves membership to the set of credentials. As provided by IDKit. See IDKit response for details.

verification_level

string

required

The verification level, as provided by IDKit. See IDKit response for details.

action

string

required

Same action identifier as passed to IDKit.

signal_hash

string

default:"hashToField('').digest"

The hash of the signal that was used to generate the proof. Defaults to the hash of an empty string.

max_age

number

default:7200

The maximum age of the root in seconds. This parameter controls how old the Merkle root used in the proof can be. Minimum value is 3600 (1 hour) and maximum value is 604800 (7 days). Defaults to 7200 (2 hours).

curl -X POST "https://developer.worldcoin.org/api/v2/verify/{app_id}" \
    -H "Content-Type: application/json" \
    -d '{
        "nullifier_hash": "0x2bf8406809dcefb1486dadc96c0a897db9bab002053054cf64272db512c6fbd8",
        "merkle_root": "0x2264a66d162d7893e12ea8e3c072c51e785bc085ad655f64c10c1a61e00f0bc2",
        "proof": "0x1aa8b8f3b2d2de5ff452c0e1a83e29d6bf46fb83ef35dc5957121ff3d3698a1119090fb...",
        "verification_level": "orb",
        "action": "my_action",
        "signal_hash": "0x00c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a4"
    }'

Possible Responses

200 OK - The proof was successfully verified.
400 Bad Request - The proof was invalid or the user has already verified for this action.

Response Examples

{
  "success": true,
  "action": "my_action",
  "nullifier_hash": "0x2bf8406809dcefb1486dadc96c0a897db9bab002053054cf64272db512c6fbd8",
  "created_at": "2023-02-18T11:20:39.530041+00:00"
}

Get Action Metadata

method

GET

https://developer.worldcoin.org/api/v1/precheck/{app_id}

Enables fetching information about a particular app to determine eligibility for verification. This endpoint is also used by the World ID Kiosk, Sign in with World ID, and World App to show metadata about the action being verified. This endpoint will only return information for active actions.

Primarily intended for internal use.

Request Body

action

string

default:""

required

The action to check. This is the same action that was passed to IDKit. Defaults to an empty string for Sign in with World ID.

nullifier_hash

string

default:""

The ZKP’s nullifier hash, as provided by IDKit. See IDKit response for details. Defaults to an empty string.

external_nullifier

string

deprecated

Deprecated. The ZKP’s external nullifier. This parameter is deprecated and will be removed in a future release, and should no longer be used. Instead, pass the action parameter.

curl -X POST "/api/v1/precheck/{app_id}" \
     -H "Content-Type: application/json" \
     -d '{
             "action": "my_custom_action",
             "nullifier_hash": "0x2bf8406809dcefb1486dadc96c0a897db9bab002053054cf64272db512c6fbd8",
             "external_nullifier": "0x00949dd9a8c5b600304d010ce3a3cf012352070ae4b77504e17af77ee894cda"
         }'

Response

__typename

string

default:"app"

Always returns app.

string

The app_id from the Developer Portal.

engine

'cloud' | 'on-chain'

Whether the app is configured for use with Cloud or On-Chain proof verifications.

is_staging

boolean

Whether the app is a staging app. If true, the Worldcoin Simulator must be used to verify.

is_verified

string

Whether the app has been verified by Worldcoin.

name

string

The app’s name as configured in the Developer Portal.

verified_app_logo

string

The URL of the app’s logo. Only returned if the app has been verified, otherwise returns an empty string.

Whether the action request is for Sign in with World ID.

can_user_verify

'yes' | 'no' | 'on-chain' | 'undetermined'

If the user is eligible to verify for this action.

“yes”: The user has not reached the maximum number of verifications for this action based on the nullifier_hash provided. Always returned when is_sign_in is true.
“no”: The user has reached the maximum number of verifications for this action based on the nullifier_hash provided.
“undetermined”: A nullifier_hash was not provided, so the user’s eligibility cannot be determined.
“on-chain”: The app is configured for On-Chain verifications, so the user’s eligibility cannot be determined. Verification eligibility is determined solely by the application’s smart contract.

action

object

Information about the action being verified.

name: The action’s human-readable name as configured in the Developer Portal.
action: The action identifier as configured in the Developer Portal. Typically a slugified version of the action’s name.
description: The action’s description as configured in the Developer Portal.
max_verifications: The maximum number of verifications allowed for this action. Will be 0 if the action is configured for unlimited verifications.
max_accounts_per_user: The maximum number of accounts allowed per user for Sign in with World ID. Will always be 1.
external_nullifier: The action’s external nullifier. Intended for internal use only.
status: Will return active if the action is active, otherwise will return inactive.
__typename: Always returns action.

Response Examples

{
  "id": "app_staging_4cfd049031b0da1e8b62084b09a9f430",
  "is_staging": true,
  "is_verified": false,
  "name": "Default App",
  "verified_app_logo": "",
  "engine": "cloud",
  "__typename": "app",
  "sign_in_with_world_id": true,
  "can_user_verify": "yes",
  "action": {
    "external_nullifier": "0x00949dd9a8c5b600304d010ce3a3cf012352070ae4b77504e17af77ee894cda",
    "name": "My action",
    "action": "my_custom_action",
    "description": "My action",
    "max_verifications": 0,
    "max_accounts_per_user": 1,
    "__typename": "action"
  }
}

Get JWK Keys

method

GET

https://developer.worldcoin.org/api/v1/jwks

This endpoint lets you retrieve the JWKs (public keys) used to verify the signature on JSON web tokens that authenticate a verification request from the Developer Portal. This verification method is only used if you are using the Hosted page user interface.

curl /api/v1/jwks

Response

{
  "keys": [
    {
      "e": "AQAB",
      "n": "09ETz2k4_9IbDBYK_Tcr6DzbDdJPeqIgvoeUvXNVjNU8mYzFbhdqh8jRH80FwtuoFqyw5oyuG9ILHxfGaG_SeutPWSxBsqulXhxTnTAx2i8HtF0i2toMuvsEtiAjQ3hD4_w2xInBVOO98WAGcNA_UgWAG2DlWpe2km_V5bv3iKteCsSTZtzT3RjEO6FeOlVr8rmx9EGwWITdPIvrEXm_3REFqvDOnQvLu2-Au8m1V3U_6404m4RV_wlWGPnhHfG57VTkkqjgrnFKGUDniG-VMJs-WFX4VIQRvy2z1A5nQsmYpobK_clGyV0D0i5P1A_lmWGDEXBLSjEW9zH_o0d2DQ",
      "kty": "RSA",
      "kid": "jwk_8934bcc47ec5b86dd490cc2a46f18a5e"
    }
  ]
}

Authenticated Endpoints

You can generate API Keys on the My Team page of the Developer Portal.

API keys are intended for use by third-party applications and for server-to-server communication. They are long-lived and can be revoked at any time.
API keys are scoped to a team and have full permissions for any actions as any user of the Developer Portal.
Once you have an API key, use it as the value of the Authorization header in your requests. For example:

Authorization: Bearer $API_KEY

GraphQL

method

POST

https://developer.worldcoin.org/api/v1/graphql

Interaction with the Developer Portal API is mostly done through a GraphQL endpoint, which enables retrieving information and interacting with any of the API objects. You can read more about queries and mutations for GraphQL to help you construct your query.

curl -X POST "/v1/graphql" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $WORLD_ID_TOKEN" \
     -d '{
           "query": "YOUR_GRAPHQL_QUERY_HERE"
         }'

Example Queries

query MyApps {
  app {
    id
    name
  }
}

Introduction

ID Kit

Sign in with World ID

Technical Reference

Base URL

Verify Proof

Request Body

Possible Responses

Response Examples

Get Action Metadata

Request Body

Response

Response Examples

Get JWK Keys

Response

Authenticated Endpoints

GraphQL

Example Queries

Introduction

ID Kit

Sign in with World ID

Technical Reference

​Base URL

​Verify Proof

​Request Body

​Possible Responses

​Response Examples

​Get Action Metadata

​Request Body

​Response

​Response Examples

​Get JWK Keys

​Response

​Authenticated Endpoints

​GraphQL

​Example Queries

Base URL

Verify Proof

Request Body

Possible Responses

Response Examples

Get Action Metadata

Request Body

Response

Response Examples

Get JWK Keys

Response

Authenticated Endpoints

GraphQL

Example Queries