World Developer Docs

@worldcoin/idkit-core is the lowest-level JavaScript/TypeScript IDKit SDK. Use it when you want full control over UI and state management or when you’re not using React.

Install

npm i @worldcoin/idkit-core

pnpm add @worldcoin/idkit-core

yarn add @worldcoin/idkit-core

Entry points

IDKit.request(config) for uniqueness proofs
IDKit.requestWithInviteCode(config) for invite-code mode
orbLegacy, secureDocumentLegacy, documentLegacy, selfieCheckLegacy for presets

Each entry point returns a builder. Finalize it with .preset(...).

Request config

import { IDKit } from "@worldcoin/idkit-core";

const builder = IDKit.request({
  app_id: "app_xxxxx",
  action: "my-action",
  rp_context: {
    rp_id: "rp_xxxxx",
    nonce: "0x...",
    created_at: 1735689600,
    expires_at: 1735689900,
    signature: "0x...",
  },
  allow_legacy_proofs: true,
  environment: "production", // Only set this to staging for testing with the simulator
  return_to: "myapp://verify-done", // Optional: mobile deep-link callback URL
  bridge_url: undefined, // Optional: custom bridge URL
});

Generate rp_context in your backend only. Never expose your RP signing key in client code.

Presets

import { IDKit, orbLegacy } from "@worldcoin/idkit-core";

const request = await IDKit.request({
  app_id: "app_xxxxx",
  action: "my-action",
  rp_context,
  allow_legacy_proofs: true,
}).preset(orbLegacy({ signal: "user-123" }));

Polling and status

After .preset(...), you get an IDKitRequest object:

connectorURI
requestId
pollOnce()
pollUntilCompletion({ pollInterval, timeout })
getDebugReport()

import { IDKitErrorCodes } from "@worldcoin/idkit-core";

const completion = await request.pollUntilCompletion({
  pollInterval: 2_000,
  timeout: 120_000,
});

if (!completion.success) {
  if (completion.error === IDKitErrorCodes.Timeout) {
    // UI timeout handling
  }
  if (completion.error === IDKitErrorCodes.Cancelled) {
    // User/app cancellation handling
  }
}

When running inside World App, native transport is used and connectorURI may be empty. Outside World App, connectorURI is the URL you render as a QR code.

Debug report

Both IDKitRequest and IDKitInviteCodeRequest expose getDebugReport(): IDKitDebugReport with diagnostics for the latest request state.

import type { IDKitDebugReport } from "@worldcoin/idkit-core";

const completion = await request.pollUntilCompletion();
if (!completion.success) {
  const report = request.getDebugReport();
  console.error(report.transport, report.request_id, report);
}

IDKitDebugReport fields: version, package_version, transport ("bridge" | "mini_app"), generated_at, and optional request_id, request_payload, response_payload, and mini_app (MiniAppDebugInfo). For bridge transport response_payload is the decrypted plaintext response string once the request completes; for native (mini_app) transport it is a structured debug object. The mini_app object holds World App native-transport diagnostics: verify_version, platform, send_channel, minikit_subscribed, and response_channel.

setDebug(true) (or window.IDKIT_DEBUG = true) and isDebug() toggle verbose console.debug logging. This is separate from getDebugReport(), which works regardless.

Invite-code mode

Use IDKit.requestWithInviteCode(config) to open a landing page that displays both an invite code and a QR code. Validation, the returned Status shape, and the poll loop are identical to IDKit.request. See Invite-code mode for when to use it.

import { IDKit, selfieCheckLegacy } from "@worldcoin/idkit-core";

const request = await IDKit.requestWithInviteCode({
  app_id: "app_xxxxx",
  action: "my-action",
  rp_context,
  allow_legacy_proofs: true,
}).preset(selfieCheckLegacy({ signal: "user-123" }));

const connectorURI = request.connectorURI; // URL with &c=<code>&a=<app_id>
const expiresAt = request.expiresAt;       // Unix seconds
const completion = await request.pollUntilCompletion();

IDKitInviteCodeRequest exposes:

connectorURI
expiresAt
requestId
pollOnce()
pollUntilCompletion({ pollInterval, timeout })
getDebugReport()

Migrating from QR / connect-URL

// Before — QR / connect-URL flow
const request = await IDKit.request({
  app_id: "app_xxxxx",
  action: "my-action",
  rp_context,
  allow_legacy_proofs: true,
}).preset(orbLegacy({ signal: "user-123" }));

const connectorURI = request.connectorURI;   // render as QR
const completion = await request.pollUntilCompletion();

// After — invite-code mode
const request = await IDKit.requestWithInviteCode({
  app_id: "app_xxxxx",
  action: "my-action",
  rp_context,
  allow_legacy_proofs: true,
}).preset(selfieCheckLegacy({ signal: "user-123" }));

const connectorURI = request.connectorURI;   // display to user (URL with code embedded)
const expiresAt = request.expiresAt;         // drive a countdown
const completion = await request.pollUntilCompletion();

The config object is unchanged. The connectorURI now includes &c=<code>&a=<app_id> params; use it alongside expiresAt in your UI. Polling, proof verification, and nullifier storage stay the same.

Server-side helpers

Use subpath exports on your backend:

import { signRequest } from "@worldcoin/idkit-core/signing";
import { hashSignal } from "@worldcoin/idkit-core/hashing";

const { sig, nonce, createdAt, expiresAt } = signRequest({
  signingKeyHex: process.env.RP_SIGNING_KEY!,
  action: "my-action",
  ttl: 300, // optional, default 300s
});

const signalHash = hashSignal("user-123");

signRequest should only run in trusted server environments. See RP Signatures for the full algorithm and test vectors.

Overview

IDKit

Credentials

Migration

Technical Reference

JavaScript

Install

Entry points

Request config

Presets

Polling and status

Debug report

Invite-code mode

Migrating from QR / connect-URL

Server-side helpers

​Install

​Entry points

​Request config

​Presets

​Polling and status

​Debug report

​Invite-code mode

​Migrating from QR / connect-URL

​Server-side helpers

​Related pages

Install

Entry points

Request config

Presets

Polling and status

Debug report

Invite-code mode

Migrating from QR / connect-URL

Server-side helpers

Related pages