diff --git a/world-id/idkit/credentials.mdx b/world-id/idkit/credentials.mdx index 7c1d876..b18ea07 100644 --- a/world-id/idkit/credentials.mdx +++ b/world-id/idkit/credentials.mdx @@ -4,7 +4,7 @@ title: "Configure Credentials" "twitter:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png" --- -{/* cspell:ignore NFC liveness */} +{/* cspell:ignore NFC eID liveness */} A [Credential](https://docs.rs/world-id-primitives/latest/world_id_primitives/credential/struct.Credential.html) is a statement an issuer makes about a World ID holder. In IDKit, the credential you request determines what the user proves to your application. @@ -15,6 +15,7 @@ A [Credential](https://docs.rs/world-id-primitives/latest/world_id_primitives/cr | Proof of Human | The user is a unique human, backed by anonymous biometric verification by the Orb. | `proofOfHuman` | | Passport | The user holds a verified NFC passport credential. | `passport` | | Selfie Check | A low-assurance biometric credential using the device camera for liveness and facial similarity. | `selfieCheckLegacy` today. World ID 4.0 support is rolling out soon. | +| Identity Check | An attestation that a document-backed property about the user matches your requested attributes. | `identityCheck` with attributes like `minimum_age`, `nationality`, or `document_type`. | You can also add a liveness check to any preset with `require_user_presence`. @@ -24,7 +25,7 @@ You can also add a liveness check to any preset with `require_user_presence`. # SDK presets -This page focuses on preset helpers for common credential requests: `proofOfHuman`, `passport`, `selfieCheckLegacy`, and the legacy presets. +This page focuses on preset helpers for common credential requests: `proofOfHuman`, `passport`, `selfieCheckLegacy`, `identityCheck`, and the legacy presets. The snippets below use `rp_context` as if it was already generated and signed by your backend. See [Integrate IDKit](/world-id/idkit/integrate) for the full RP-signing flow. @@ -141,9 +142,74 @@ const preset = selfieCheckLegacy({ signal: "user-123" }); ``` +## Identity Check (Preview) + + + Identity Check is currently in preview. If you're interested in using or learning more about Identity Check, please contact us. + + + +Identity Check lets your app ask the user to attest that document-backed attributes match your policy, without asking you to handle the underlying document data. Use it for eligibility checks such as minimum age, document type, issuing country, or nationality. You can request attributes such as: + +| Attribute | Value type | +| --- | --- | +| `document_type` | `"passport"`, `"eid"` or `"mnc"` | +| `document_number` | `string` | +| `issuing_country` | ISO 3166-1 alpha-3 country code | +| `full_name` | `string` | +| `minimum_age` | `number` | +| `nationality` | ISO 3166-1 alpha-3 country code | + + +```typescript title="JavaScript" +import { IDKit, identityCheck } from "@worldcoin/idkit-core"; + +const preset = identityCheck({ + attributes: [ + { type: "document_type", value: "passport" }, + { type: "minimum_age", value: 18 }, + ], +}); + +const request = await IDKit.request({ + app_id: "app_xxxxx", + action: "my-action", + rp_context, + allow_legacy_proofs: false, +}).preset(preset); +``` + +```tsx title="React" +import { IDKitRequestWidget, identityCheck } from "@worldcoin/idkit"; + +const preset = identityCheck({ + attributes: [ + { type: "document_type", value: "passport" }, + { type: "minimum_age", value: 18 }, + ], +}); + + { /* ... */ }} +/>; +``` + + +Successful Identity Check responses include `identity_attested` so your backend can distinguish whether the requested attributes matched. + ## User presence and liveness -`require_user_presence` asks World App to perform an additional liveness step before completing the proof. This flag works with presets. +To check for user presence and liveness, add the `require_user_presence` flag to your request. This is a request-level flag, not a credential; it asks World App for a fresh liveness check before returning the proof and fails with `user_presence_failed` if the check is not completed. + +Depending on the credential requested, World App matches the user's live selfie to the credential image, such as the passport photo or the image captured during Orb verification. ```typescript title="JavaScript" @@ -180,23 +246,62 @@ const preset = proofOfHuman({ signal: "user-123" }); ``` -If the user does not complete the liveness step, the request fails with `user_presence_failed`. - ## Other legacy presets These presets only return World ID 3.0 proofs. Keep them for existing integrations or when you specifically need the older verification level. -| Preset | What it requests | -| --- | --- | -| `orbLegacy` | Orb verification. | -| `secureDocumentLegacy` | At least a Secure Document verification. Returns the user's highest legacy credential: Secure Document or Orb. | -| `documentLegacy` | At least a Document verification. Returns the user's highest legacy credential: Document, Secure Document, or Orb. | -| `deviceLegacy` | At least a Device verification. Returns the user's highest legacy credential: Device, Document, Secure Document, or Orb. | + + + + + + + + + + + + + + + + + + + + + + + + + +
PresetWhat it requests
orbLegacyOrb verification.
secureDocumentLegacyAt least a Secure Document verification. Returns the user's highest legacy credential: Secure Document or Orb.
documentLegacyAt least a Document verification. Returns the user's highest legacy credential: Document, Secure Document, or Orb.
deviceLegacyAt least a Device verification. Returns the user's highest legacy credential: Device, Document, Secure Document, or Orb.
## Common parameters -| Parameter | Where it is used | Description | -| --- | --- | --- | -| `signal` | Presets | Binds application context into the proof, such as a user ID or wallet address. Your backend should enforce the same value. | -| `allow_legacy_proofs` | Request config and widgets | Required for request flows. Set to `true` while accepting World ID 3.0 fallback proofs; set to `false` for World ID 4.0-only requests. | -| `require_user_presence` | Request config and widgets | Optional liveness step. Defaults to `false`. | + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterWhere it is usedDescription
signalPresetsBinds application context into the proof, such as a user ID or wallet address. Your backend should enforce the same value.
allow_legacy_proofsRequest config and widgetsRequired for request flows. Set to true while accepting World ID 3.0 fallback proofs; set to false for World ID 4.0-only requests.
require_user_presenceRequest config and widgetsOptional liveness step. Defaults to false.
diff --git a/world-id/idkit/error-codes.mdx b/world-id/idkit/error-codes.mdx index a9f939b..aa3dda2 100644 --- a/world-id/idkit/error-codes.mdx +++ b/world-id/idkit/error-codes.mdx @@ -12,149 +12,149 @@ This page focuses on IDKit SDK and bridge error codes returned during request fl - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - +
CodeCode Meaning Typical action
user_rejecteduser_rejected User cancelled in World App. Treat as user cancellation, allow retry.
verification_rejectedverification_rejected Legacy rejection code (older bridge/app behavior). Handle same as user_rejected.
credential_unavailablecredential_unavailable Requested credential type is not available for that user. Offer fallback credential policy or explain requirement.
world_id_4_not_availableworld_id_4_not_available World ID 4.0 credential is not available for that user. Use a compatible fallback request or explain the World ID 4.0 requirement.
world_id_3_not_availableworld_id_3_not_available World ID 3.0 credential is not available for that user. Use a compatible fallback request or explain the World ID 3.0 requirement.
malformed_requestmalformed_request Payload or configuration is invalid. Check app_id, rp_context, and request shape.
invalid_networkinvalid_network Environment mismatch between app config and World App context. Align staging/production settings.
inclusion_proof_pendinginclusion_proof_pending Credential inclusion data is not ready yet. Retry later.
inclusion_proof_failedinclusion_proof_failed Inclusion proof retrieval failed. Retry; if repeated, treat as operational incident.
unexpected_responseunexpected_response Malformed or unsupported bridge/app response. Log diagnostics and retry once.
connection_failedconnection_failed Could not establish/maintain bridge communication. Check connectivity and bridge reachability.
max_verifications_reachedmax_verifications_reached Action already verified the maximum allowed number of times. Treat as terminal business-rule outcome.
failed_by_host_appfailed_by_host_app Host app callback failed while processing a successful proof. Fix host callback/backend logic and retry.
invalid_rp_signatureinvalid_rp_signature RP signature could not be verified. Check the RP signing key, nonce, timestamps, action, and signed message.
nullifier_replayednullifier_replayed Nullifier was already used for this action. Treat as an already-verified outcome; do not retry the same action as a new verification.
duplicate_nonceduplicate_nonce RP reused a signature nonce. Generate a fresh nonce and signed RP context for each request.
unknown_rpunknown_rp RP is not known to the registry. Check the registered RP ID and app configuration.
inactive_rpinactive_rp RP is registered but inactive. Reactivate or reconfigure the RP before retrying.
timestamp_too_oldtimestamp_too_old RP request timestamp is too old. Generate a new signed RP context with a current timestamp.
timestamp_too_far_in_futuretimestamp_too_far_in_future RP request timestamp is too far in the future. Fix server clock skew and generate a new signed RP context.
invalid_timestampinvalid_timestamp RP request timestamp is invalid. Check timestamp format and regenerate the signed RP context.
rp_signature_expiredrp_signature_expired RP signature has expired. Request a fresh RP signature before starting verification.
user_presence_faileduser_presence_failed Required user-presence check was not completed. Let the user retry the request.
identity_attributes_not_matchedidentity_attributes_not_matched User identity attributes did not match the requested constraints. Show an eligibility fallback or adjust the requested attribute constraints.
generic_errorgeneric_error Catch-all unknown failure. Log details and retry with backoff.
invalid_rp_id_formatinvalid_rp_id_format RP ID is malformed. Use the registered rp_... ID from your app configuration.
timeouttimeout Client-side polling timeout. Extend timeout or let the user retry.
cancelledcancelled Client-side cancellation (abort/task cancel/user close). Treat as neutral cancellation path.