Skip to main content

​
Server — @worldcoin/human-in-the-loop

​
requestHumanAuthorization(options?)

Import from @worldcoin/human-in-the-loop/workflows. Returns a tool execute function that pauses the workflow until a World ID proof is received. Returns Promise<IDKitResult>.
OptionTypeDefaultDescription
actionstring | ((ctx) => string)toolCallIdUnique action string bound to this verification. When a function, receives { toolCallId, input }.
signingKeystringWORLD_SIGNING_KEY envHex-encoded RP signing key.
rpIdstringWORLD_RP_ID envRelying-party ID for verification.

​
Client — @worldcoin/human-in-the-loop-react

​
<HumanApproval>

Drop-in component that renders the World ID widget and posts the proof back automatically. Ships unstyled.
PropTypeDefaultDescription
messageUIMessagerequiredThe message containing the tool part.
partUIMessagePartrequiredThe tool-call part (must include toolCallId).
appId`app_${string}`NEXT_PUBLIC_WORLD_APP_ID envWorld app ID.
presetPresetorbLegacy()IDKit verification preset.
allowLegacyProofsbooleanfalseAccept v3 World ID proofs.
triggerLabelReactNode'Verify with World ID'Button label.
successContentReactNode'Approved with World ID.'Shown after verification.
classNamestring—CSS class for the outer wrapper.

​
useHumanApproval(message, part)

Headless hook for custom approval UI.
FieldTypeDescription
readybooleantrue once the approval context has streamed from the server.
actionstring | undefinedAction string. Pass to IDKitRequestWidget.
rpContextRpContext | undefinedPass to IDKitRequestWidget’s rp_context.
webhookUrlstring | undefinedWebhook URL. Handled by verify automatically.
stateHumanApprovalState'idle' | 'verifying' | 'verified' | 'error'
verify(proof: IDKitResult) => Promise<void>Wire to IDKitRequestWidget.handleVerify.
type HumanApprovalState =
  | { status: 'idle' }
  | { status: 'verifying' }
  | { status: 'verified' }
  | { status: 'error'; error: Error }