> ## Documentation Index > Fetch the complete documentation index at: https://docs.world.org/llms.txt > Use this file to discover all available pages before exploring further. # Register your application > Register and manage your World ID OIDC application, credentials, callbacks, and benefit listing. Sign in to the [developer portal](https://auth.world.org/portal) 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 1. **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. 2. **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. 3. **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](https://docs.world.org/agent-pass/xaa.md) 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](https://docs.world.org/agent-pass/connect-your-backend.md). When you create the client, choose its [accepted accounts](https://docs.world.org/agent-pass/step-up.md#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](https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg). 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](https://docs.world.org/agent-pass/build-with-a-coding-agent.md#give-your-coding-agent-the-guide) without a plugin or MCP connection. Optionally [connect developer MCP tools](https://docs.world.org/agent-pass/build-with-a-coding-agent.md#connect-your-coding-agent) 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](https://docs.world.org/agent-pass/build-with-a-coding-agent.md) 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.