Client setup

Sign in to the developer portal (opens in a new tab) with Google to register an OIDC client for your application or auth server. This registration supports step-up, human-in-the-loop workflows, and primary sign-in.

Check that your Google account is eligible for self-service registration in the target environment. Registration may be disabled, or you may have reached the limit on clients you can own. If you receive account_not_eligible, contact the environment's operator for help.

Register your application

Register your callback URL. Use HTTPS callback URLs. Callback hosts must be ASCII; use Punycode for an internationalized domain. Match the scheme, path, query, and port exactly; wildcards and variable ports are not supported. Device-only clients also need a registered redirect URI, although the device grant does not use it.
Choose client authentication. Register client_secret_basic, client_secret_post, or private_key_jwt. The method is fixed for the client's lifetime; register a new client to switch methods. You can rotate the existing client's secret or signing keys. For private_key_jwt, generate the key pair in your backend's secure environment and register only its public JWKS.
Save the credentials in your backend. Save the client ID and, when using a shared secret, the secret shown once by the portal. Keep shared secrets and private keys exclusively in your backend. Client secrets start with worldidp_client_secret_, so secret scanners can flag leaked ones.

World ID authentication with openid requires a client registered through the portal. Agent hosts that use XAA may instead use public or confidential CIMD registration. OIDC dynamic client registration (DCR) is not supported.

Use Google sign-in to manage clients in the portal. Your application's users authenticate through the separate OIDC flow.

Once registered, connect your backend or auth server with OIDC. When you create the client, choose its accepted accounts for requests that omit both acr_values and an acr claim request.

Client authentication

Authenticate at the token and device authorization endpoints with the client's registered method:

Method	How to send credentials
`client_secret_basic` (portal default)	Form-encode the client ID and secret and send them in the Authorization header as Basic credentials. An optional body `client_id` must match.
`client_secret_post`	Send `client_id` and `client_secret` in the form body, without an Authorization header.
`private_key_jwt`	Send `client_id`, `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer`, and `client_assertion` in the form body, without an Authorization header.

For private_key_jwt, register the public JWKS in the portal and keep the private key in your backend. The assertion is a compact RS256 JWT:

kid selects a registered RSA key (2048–8192 bits). It may be omitted when exactly one key is registered.
iss and sub are both the client ID.
The single aud is https://auth.world.org or the exact endpoint being called.
Include iat, exp (at most one hour after iat), and a unique jti of at most 256 bytes. Expiration is strict; iat and optional nbf allow 30 seconds of clock skew.

Use a fresh assertion for every request, retry, and device poll, including after authorization_pending. Assertions are single-use across endpoints. A rejected assertion returns HTTP 400 invalid_client. Keep request bodies, Authorization headers, and callback query strings out of logs.

Manage credentials and callbacks

When rotating credentials, keep the old secret or key active until the new one works; changes can take a short time to propagate.

New portal applications receive a unique, permanent identity sector by default. World IdP's managed sectors extend the hostname-based sector selection in OIDC Core §8.1 (opens in a new tab). Callbacks can use different hostnames without a hosted sector document. Applications in different sectors receive different pairwise sub values and relay aliases, even when their callbacks use the same hostname. Existing applications keep their current sectors and account identifiers.

To share identifiers, enable identity sharing in a managed-sector application's settings, then select it when registering another application. You must own every application in that sector; being a member is not enough. Shared-sector applications cannot transfer ownership individually. Deleting an application does not make its sector available for reuse. Disabling sharing prevents new applications from joining through that source; existing applications and credentials remain unchanged.

New portal registrations cannot choose a host-based sector. Hosted sector documents are no longer fetched or editable. Existing host-based applications keep their sectors and registered callbacks. A new client cannot join a legacy host-based sector. Keep using the existing client to preserve those identifiers, or link accounts explicitly when moving to a new managed sector.

Change callbacks: register each new exact URI before using it. Managed sectors stay unchanged across hostname changes. For an existing host-based client, only newly added callbacks must use the stored sector hostname; existing callbacks can be retained, reordered, or removed. Hostname comparison ignores case and a trailing dot; subdomains are distinct.
Move to another sector: create a separate client. An existing client's sector cannot change, and deleting and recreating a client does not migrate your application's account mappings or permissions.

Rotating credentials does not change subjects. Registering a new application changes subjects unless you explicitly share its sector. Changing the issuer changes the identity namespace.

When migrating to a new sector, retain the old account mapping during the transition. Require an authenticated session for the existing application account and a fresh, browser-bound World ID linking attempt for the new client. Confirm the intended account with the user, then store the new validated (iss, sub) only after linking succeeds. Establish each mapping through this validated linking flow.

Get help from a coding agent

Your coding agent can read the public integration guides without a plugin or MCP connection. Optionally connect developer MCP tools to register and manage the application. Portal tools use Google authorization, and registration and credential changes require your approval in the portal. Keep client secrets and private keys outside agent conversations. The agent instructions cover portal tool use.

Publish a benefit listing

If your application offers a World ID benefit, create a Catalog listing for its OIDC client in the developer portal. Add a name, description, and HTTPS application URL. The optional Instructions (instructions) field can include steps to claim the benefit, a plugin link, or an MCP URL. Include prerequisites and explain how to recognize success. Keep these public instructions free of credentials and tokens. The owner submits the listing for review. Only an approved, published listing for an active client appears in get_benefits. Changes to instructions require a new review. Publication changes can take up to a minute to appear.

Agents use the instructions to understand the partner's preferred claiming flow, or start at the app URL if no instructions are supplied. Your application enforces eligibility, authorization, and redemption. The application URL is separate from the OIDC callback.