Technical Reference
Sign in with World ID Reference
Base domain
https://id.worldcoin.org
This page primarily describes options that are OIDC-compliant. We additionally support using access tokens as described in the OAuth2 standards. No actions can be taken on behalf of a user with OAuth2 access tokens, but you may retrieve the same information about a user as would be contained in an id_token
. See below for details.
OpenID Connect discovery
Fetches the OpenID Connect discovery document.
Common Errors
method_not_allowed
: HTTP method is not allowed. Only GET and OPTIONS may be used
Request
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",
"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"]
}
Authorize
Redirect your users to this page to begin the sign-in flow.
Required attributes
All attributes are formatted as URL query parameters.
- Name
response_type
- Type
- string
- Description
Must be
code
for authorization code flow,id_token
for implicit flow, or a space-separated combination ofcode
,id_token
, andtoken
for hybrid flow. We generally recommend using the authorization code or implicit flows.
- Name
scope
- Type
- string
- Description
Space-separated list of the requested OIDC scopes. Must include
openid
, and may optionally includeemail
andprofile
.
- Name
client_id
- Type
- string
- Description
The Client ID of your app. Get this from the Developer Portal.
- Name
redirect_uri
- Type
- string
- Description
URL the user will be redirected to after authentication. Must match one of your app's configured
redirect_uris
.
Optional attributes
- Name
state
- Type
- string
- Description
An opaque value used to maintain state between the request and the callback.
- Name
nonce
- Type
- string
- Description
Required when using the implicit flow. Used to prevent replay attacks. Should be randomly generated for each sign-in, and checked to ensure it's unchanged after the callback.
- Name
response_mode
- Type
- string
- Description
Determines how the authorization code, ID token, and/or access token are returned. Must be one of
query
,fragment
, orform_post
.query
is only supported for the authorization code flow. Defaults toquery
for authorization code flow, andfragment
for all others.
Common Errors
required
: A necessary attribute was not set. Required attributes are:response_type scope client_id redirect_uri
invalid_redirect_uri
: The provided redirect URI is invalid. Ensure you've set the correctredirect_uri
in the Developer Portal.
Request
https://id.worldcoin.org/authorize?redirect_uri=https%3A%2F%2Fdocs.worldcoin.org%2Fworld-id%2Ftry-callback&response_type=code&scope=openid+profile+email&client_id=app_ce4cb73cb75fc3b73b71ffb4de178410
Response
https://example.app/api/auth/callback/worldcoin?code=e777d780f437330bbd79535b
Exchange Code
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
.
- Name
redirect_uri
- Type
- string
- Description
The same redirect URI used in the
/authorize
request.
Common Errors
method_not_allowed
: HTTP method is not allowed. Only POST and OPTIONS may be usedinvalid_content_type
: The provided content type is invalid, onlyapplication/x-www-form-urlencoded
is supportedunauthenticated
: The provided authorization token is invalid, try checking your credentialsinvalid_grant_type
: The provided grant type is invalid, onlyauthorization_code
is supportedrequired
: 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
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&redirect_uri=https%3A%2F%2Fdocs.worldcoin.org%2Fapi%2Fauth"
Response
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a1.ey8yZmVi.ZjY3MDc3N2UyY2NlNzY5YzUxOG...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "openid",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Imp3a1.ey8yZmVi.ZjY3MDc3N2UyY2NlNzY5YzUxOG..."
}
OAuth2
If you selected token
as one of your response_types
for the /authorize
endpoint, you'll receive an OAuth2 access token. Typically an access token would allow you to perform certain actions on a user's behalf, but there are no actions to perform for a user in this case.
You can retrieve the same information about a user with an access token as you'd receive in an ID token. While we support this functionality for broader compatibility, we generally recommend using the authorization code or implicit flows, rather than the hybrid flow.
The endpoints below are only used with an OAuth2 access token.
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. You obtain your client_id (also called app_id) and client_secret from the Developer Portal.
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 usedinvalid_content_type
: The provided content type is invalid, onlyapplication/x-www-form-urlencoded
is supportedrequired
: A necessary attribute was not set. Required attributes are:token
unauthenticated
: The authorization header is missing, please pass the Bearer authorization tokeninvalid_token
: The authorization token was invalid, and may be expired. Try generating a new token via/token
Request
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
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 usedunauthenticated
: The authorization header is missing, please pass the Bearer authorization tokeninvalid_token
: The authorization token was invalid, and may be expired. Try generating a new token via/token
Request
curl -X POST https://id.worldcoin.org/userinfo \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZ.eyCI6I.mp3a18yZmViZjY3MDc3N2UyY2NlN..."
Response
{
"sub": "0x2ae86d6d747702b3b2c81811cd2b39875e8fa6b780ee4a207bdc203a7860b535",
"https://id.worldcoin.org/beta": { // deprecated, will be removed in the future
"likely_human": "strong",
"credential_type": "orb"
},
"https://id.worldcoin.org/v1": {
"verification_level": "orb", // "orb" or "device"
},
// if `email` scope is included:
"email": "0x2ae86d6d747702b3b2c81811cd2b39875e8fa6b780ee4a207bdc203a7860b535@id.worldcoin.org",
// if `profile` scope is included:
"name": "World ID User",
"given_name": "World ID",
"family_name": "User"
}