Technical Reference

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

Verify Proof

POST/v1/verify/{app_id}

Enables you to verify a World ID proof for a Cloud action. To ensure human-uniqueness, a single person can only verify once for every action. If you send a proof for the same user twice, an error will be returned.

Required attributes

Name
action
Type
string
Description
Same action identifier as passed to IDKit.
Name
signal
Type
string
Description
Same signal as passed to IDKit.
Name
nullifier_hash
Type
string
Description
The unique user identifier (called the nullifier hash in the ZKP), as provided by IDKit. See IDKit response for details.
Name
proof
Type
string
Description
The zero-knowledge proof, as provided by IDKit. See IDKit response for details.
Name
merkle_root
Type
string
Description
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.
Name
credential_type
Type
string
Description
The credential type, as provided by IDKit. See IDKit response for details.

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.

Request

POST

/api/v1/verify/{app_id}

curl -X POST "/api/v1/verify/{app_id}" \
    -H "Content-Type: application/json" \
    -d '{
        "nullifier_hash": "0x2bf8406809dcefb1486dadc96c0a897db9bab002053054cf64272db512c6fbd8",
        "merkle_root": "0x2264a66d162d7893e12ea8e3c072c51e785bc085ad655f64c10c1a61e00f0bc2",
        "proof": "0x1aa8b8f3b2d2de5ff452c0e1a83e29d6bf46fb83ef35dc5957121ff3d3698a1119090fb...",
        "credential_type": "orb",
        "action": "my_action",
        "signal": "my_signal"
    }'

Response

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

Get Action Metadata

GET/v1/precheck/{app_id}

Enables fetching information about a particular app to determine eligibility for verification. This endpoint is also used by the kiosk and World mobile app to show metadata about the action being verified. This endpoint will only return information for active actions.

Name
action
Type
string
Description
The action to check. This is the same action that was passed to IDKit.
Name
nullifier_hash
Type
string
Description
The ZKP's nullifier hash, as provided by IDKit. See IDKit response for details.
Name
external_nullifier
Type
string
Description
The ZKP's external nullifier.

Request

GET

/api/v1/precheck/{app_id}

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

{
	"id": "app_staging_4cfd049031b0da1e8b62084b09a9f430",
	"is_staging": true,
	"is_verified": false,
	"logo_url": "",
	"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

GET/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

API Keys

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

POST/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.

Example Queries

query MyApps {
	app {
		id
		name
	}
}

Request

POST

/api/v1/graphql

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