Technical Reference

Sign In with Worldcoin Reference

Base domain

https://id.worldcoin.org

OpenID Connect discovery

GET/.well-known/openid-configuration

Fetches the OpenID Connect discovery document.

Common Errors

method_not_allowed: HTTP method is not allowed. Only GET and OPTIONS may be used

Request

GET

/.well-known/openid-configuration

curl https://id.worldcoin.org/.well-known/openid-configuration

Response

{
    "issuer": "https://id.worldcoin.org",
    "authorization_endpoint": "https://id.worldcoin.org/authorize",
    "token_endpoint": "https://id.worldcoin.org/token",
    "userinfo_endpoint": "https://id.worldcoin.org/userinfo",
    "registration_endpoint": "https://id.worldcoin.org/register",
    "jwks_uri": "https://id.worldcoin.org/jwks",
    "scopes_supported": ["openid", "email", "profile"],
    "response_types_supported": ["code", "id_token", "id_token token", "code id_token"],
    "grant_types_supported": ["authorization_code", "implicit"],
    "subject_types_supported": ["pairwise"],
    "id_token_signing_alg_values_supported": ["RSA"]
}

Register App

POST/register

Registers a new application for use with Sign In with World ID.

Required attributes

Name
redirect_uris
Type
string
Description
URLs the user will be redirected to after authentication. Must be HTTPS, and can always be updated in the Developer Portal.

Optional attributes

Name
client_name
Type
string
Description
Name of the application. This is displayed to the user during authentication.
Name
logo_uri
Type
string
Description
URL to the application's logo. This is displayed to the user during authentication.
Name
application_type
Type
string
Description
Type of application. Can be either web or mobile. Defaults to web.
Name
grant_types
Type
string
Description
Grant types the application is allowed to use. Can be either authorization_code, implicit, hybrid. Defaults to authorization_code.

Common Errors

method_not_allowed: HTTP method is not allowed. Only POST and OPTIONS may be used
required: A necessary attribute was not set. Required attributes are: redirect_uris
invalid_redirect_uri: The provided redirect URI is invalid, either HTTPS was not used or the URL was malformed

Request

POST

/register

curl -X POST https://id.worldcoin.org/register \
    -H "Content-Type: application/json" \
    -d '{
        "client_name": "Example Application",
        "logo_uri": "https://app.example.com/logo.svg",
        "redirect_uris": ["https://app.example.com/callback", "https://app.example.com/redirect"],
        "application_type": "web",
        "grant_types": "authorization_code",
        "response_types": "code"
    }'

Response

{
    "application_type": "web",
    "client_id": "app_staging_7550e829082fc558e112e0620c1c7a59",
    "client_id_issued_at": "2023-03-09T00:58:52.5011+00:00",
    "client_name": "Example Application",
    "client_secret": "sk_6a2ff697607b77d641fbb10101b7636f3e6c750f2aac3652",
    "client_secret_expires_at": 0,
    "grant_types": "authorization_code",
    "logo_uri": "https://app.example.com/logo.svg",
    "response_types": "code"
}

Exchange Code

POST/token

Exchanges an authorization code for an id_token for the given user.

Required attributes

Name
code
Type
string
Description
The authorization code to exchange.
Name
grant_type
Type
string
Description
The type of grant to exchange. Must be authorization_code.

Common Errors

method_not_allowed: HTTP method is not allowed. Only POST and OPTIONS may be used
invalid_content_type: The provided content type is invalid, only application/x-www-form-urlencoded is supported
unauthenticated: The provided authorization token is invalid, try checking your credentials
invalid_grant_type: The provided grant type is invalid, only authorization_code is supported
required: A necessary attribute was not set. Required attributes are: code
invalid_grant: The authorization code was invalid, and may be expired. Try generating a new code via /authorize

Request

POST

/token

curl -X POST https://id.worldcoin.org/token \
     -H "Authorization: Basic YXBwXzU1MGU4MjkwODJmYzU1OGUxMTJlMDYyMGMxYzdhNT..." \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "code=23e5edda0f731dfdddace390&grant_type=authorization_code"

Response

{
	"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a1.ey8yZmVi.ZjY3MDc3N2UyY2NlNzY5YzUxOG...",
	"token_type": "Bearer",
	"expires_in": 3600,
	"scope": "openid",
	"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a1.ey8yZmVi.ZjY3MDc3N2UyY2NlNzY5YzUxOG..."
}

Introspect

POST/introspect

Validates the given access token is active for the user.

For introspect, Basic Authentication is used. The Authorization header contains the word "Basic ", followed by a base64 encoding of the "client_id:client_secret" values returned from the /register endpoint.

Required attributes

Name
token
Type
string
Description
The access token to validate.

Common Errors

method_not_allowed: HTTP method is not allowed. Only POST may be used
invalid_content_type: The provided content type is invalid, only application/x-www-form-urlencoded is supported
required: A necessary attribute was not set. Required attributes are: token
unauthenticated: The authorization header is missing, please pass the Bearer authorization token
invalid_token: The authorization token was invalid, and may be expired. Try generating a new token via /token

Request

POST

/introspect

curl -X POST https://id.worldcoin.org/introspect \
  -H "Authorization: Basic YXBwXzU1MGU4MjkwODJmYzU1OGUxMTJlMDYyMGMxYzdhNT..." \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a18yZmViZjY3MDc3N2UyY2NlNzY5YzUxOGM3MDNkNTNjMStN..."

Response

{
	"active": true,
	"client_id": "app_staging_7550e829082fc558e112e0620c1c7a59",
	"exp": 1678330528,
	"sub": "0x2ae86d6d747702b3b2c81811cd2b39875e8fa6b780ee4a207bdc203a7860b535"
}

Get User Info

POST/userinfo

Retrieves all user information, based on the approved scopes, with the given access token.

For userinfo, Bearer Authentication is used. The Authorization header contains the word "Bearer ", followed by the access token returned from the /token endpoint.

Common Errors

method_not_allowed: HTTP method is not allowed. Only GET, POST, and OPTIONS may be used
unauthenticated: The authorization header is missing, please pass the Bearer authorization token
invalid_token: The authorization token was invalid, and may be expired. Try generating a new token via /token

Request

POST

/userinfo

curl -X POST https://id.worldcoin.org/userinfo \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZ.eyCI6I.mp3a18yZmViZjY3MDc3N2UyY2NlN..."

Response

{
	"sub": "0x2ae86d6d747702b3b2c81811cd2b39875e8fa6b780ee4a207bdc203a7860b535",
	"https://id.worldcoin.org/beta": {
		"likely_human": "strong",
		"credential_type": "orb"
	},
	"email": "0x2ae86d6d747702b3b2c81811cd2b39875e8fa6b780ee4a207bdc203a7860b535@id.worldcoin.org",
	"name": "World ID User",
	"given_name": "World ID",
	"family_name": "User"
}