Integrate Reclaim Protocol end to end using our agent
logoReclaim Protocol Docs

Anatomy of messages

Datastructures of messages transmitted during the verification process

Proof Request

{
    // This can be your application id
    "applicationId": "0xsampleapplicationid",
    // The ID of Provider you are using for verifications
    "providerId": "example",
    // A unique short sessionId created by Reclaim Protocol to identify this session
    "sessionId": "123",
    // Any JSON serializable data you want to be part of the proof generation process
    "context": {
      "user": "john@example.com",
      "contextAddress":"Address you set",
      "contextMessage":"message you set"
    },
    // URL where proof(s) are submitted after all proofs are successfully generated
    "appCallbackUrl": "https://api.example.com/success?session=def",
    // The type of claim creation
    "claimCreationType": "createClaim",
    // The parameters used by the provider script and the requests involved in proof generation process
    // This is a map of strings to strings.
    "parameters": {
        "user": "john@example.com"
    },
    // Signature of the proof request using your application secret
    // This signature is generated using your application secret to know it came from your application
    "signature": "0xbbf1aad7bd65c6d0c37a5b6012c4dff217e190372d5e364bf8f2bf4ea9df3a080ec8b325b84b29e130d9b15401087b36bc4852367c8f93427c39ffb7b44b498d1c",
    // URL to redirect to after successful proof generation
    "redirectUrl": "https://example.com/success?session=def",
    // Optional. Only applicable when `redirectUrl` is provided.
    "redirectUrlOptions": {
        // `POST` method only supported on In-Browser SDK.
        // Allowed values: GET, POST. Optional. Default is GET.
        "method": "POST",
        // An array of objects with `name` (string) and `value` (string) fields for form submission.
        // `body` is only supported on In-Browser SDK.
        // Optional. Only applicable when `method` is `POST`.
        "body": [
            {
                "name": "username",
                "value": "john"
            },
            {
                "name": "student",
                "value": "true"
            }
        ]
    },
    // URL which is called when verification is cancelled by the user or after errors (only auto submit enabled; auto submit is enabled by default).
    "cancelCallbackUrl": "https://api.example.com/cancel?session=def",
    // URL to redirect to after cancelled proof generation
    "cancelRedirectUrl": "https://example.com/cancelled?session=def",
    // Optional. Only applicable when `cancelCallbackUrl` is provided.
    "cancelRedirectUrlOptions": {
        // `POST` method only supported on In-Browser SDK.
        // Allowed values: GET, POST. Optional. Default is GET.
        "method": "POST",
        // An array of objects with `name` (string) and `value` (string) fields for form submission.
        // `body` is only supported on In-Browser SDK.
        // Optional. Only applicable when `method` is `POST`.
        "body": [
            {
                "name": "username",
                "value": "john"
            },
            {
                "name": "student",
                "value": "true"
            }
        ]
    },
    // Timestamp of the proof request
    "timestamp": "1769867597546",
    // legacy: same as above
    "timeStamp": "1769867597546",
    "options": {
        // enables diagnostic logging for debugging purposes
        "log": true,
        // enables use of AI in verification journey
        "acceptAiProviders": false,
        // users may use Reclaim Verifier app clip or instant app for verification
        "useAppClip": false,
        // URL of the custom share page (optional)
        "customSharePageUrl": "https://portal.reclaimprotocol.org",
        "launchOptions": {
            // enables deferred deep links flow
            "canUseDeferredDeepLinksFlow": true
        },
        // Enables auto submitting proofs on success or errors
        "canAutoSubmit": false,
        // Preferred locale for the UI in verification journey
        "preferredLocale": "zh-Hant-HK",
        // Metadata that can be used by the UI in verification journey
        "metadata": {
            // This is an example of metadata, actual values may depend on custom themes
            "theme": "dark"
        },
        // Enables use of browser extension for verification
        "useBrowserExtension": true
    },
    // The version of SDK that generated this JSON string request
    "sdkVersion": "js-4.11.0",
    // Whether to submit proof as JSON or URL encoded using HTTP POST to the success callback. Cancellation callback not affected.
    "jsonProofResponse": false,
    // The version of provider that should be used for verifications
    "resolvedProviderVersion": "1.0.0"
}

Proof

[ // note this is an array
  {
    "identifier": "0x7059eb0d834e4e0b544f683ef083081fa7dc7f51b847b5ccb67c5b63a7e8b605",
    "claimData": {
      "provider": "http",
      "parameters": "",
      "owner": "0x1234567890123456789012345678901234567890", //Legacy. Ignore.
      "timestampS": 1769800037,
      // THIS IS WHAT YOU CARE ABOUT
      // "extractedParameters" will contain the data. Can be extracted from this field using `JSON.parse(proof[index].claimData.context).extractedParameters`.
      "context": "{\"contextAddress\":\"Your set address\",\"contextMessage\":\"Your context message\",\"extractedParameters\":{\"KEY\":\"Value\"}}",
      "identifier": "0x7059eb0d834e4e0b544f683ef083081fa7dc7f51b847b5ccb67c5b63a7e8b605",
      "epoch": 1
    },
    "signatures": [
      "0xc014ac88a17b1fb95ca8cb51b1bbefc02efb79d741f1b83fe011eac8dadc703722d409674a76c5bc0d51d835cf2b52db8bef22e1df69a4feecb0da9d1ab160e71b"
    ],
    "witnesses": [
      {
        "id": "0x1be31a94361a391bbafb2a4ccd704f57dc04d4bb",
        "url": "reclaimprotocol"
      }
    ],
    // Optional: Extra data attached to any proof. This can be null, JSON string, array or map. In most cases, this is a JSON map or null.
    "publicData": {
      "KEY":"VALUE"
    }
  }
]

Data dictionary

The following tables define every field returned by the SDK. Note that several fields are JSON strings that must be JSON.parsed before use — these are flagged in the "Parse?" column.

Proof

Each element of the proof array (the object above).

FieldTypeParse?Description
identifierstringUnique identifier of the claim (same value as claimData.identifier).
claimDataProviderClaimDataThe signed claim. See table below.
signaturesstring[]Attestor signature(s) over the claim.
witnessesWitnessData[]Attestor(s) that witnessed and signed the claim ({ id, url, claimAttestation? }).
extractedParameterValuesobjectConvenience map of the extracted values.
publicDataany (optional)Extra, unverified data attached by the provider. Usually a JSON map or null.
taskIdnumber (optional)Internal task identifier.
teeAttestationTeeAttestation (optional)Hardware attestation of the TEE that ran the session. See table below.

claimData (ProviderClaimData)

FieldTypeParse?Description
providerstringProvider type, e.g. "http".
parametersstring✅ JSON stringParameters used by the provider script/requests.
ownerstringLegacy — ignore.
timestampSnumberUnix timestamp (seconds) when the claim was created.
contextstring✅ JSON stringParses to the Context object below (holds extractedParameters).
identifierstringUnique identifier of the claim.
epochnumberAttestor epoch the claim was signed in.

Context (parsed from claimData.context)

const context = JSON.parse(proof.claimData.context);
FieldTypeDescription
contextAddressstringThe address you set via setContext (usually your user id).
contextMessagestringThe message you set via setContext.
reclaimSessionIdstringThe Reclaim session id — use for replay protection.
extractedParametersRecord<string, string> (optional)The verified data you care about, e.g. { email: "..." }.
providerHashstring (optional)Hash of the provider used.
attestationNoncestring (optional)Nonce binding the proof to your app + session (used by TEE attestation).
attestationNonceDataobject (optional){ applicationId, sessionId, timestamp, attestationVersion? } used to derive the nonce.

verifyProof result (VerifyProofResult)

A discriminated union on isVerified. On success, data/publicData are populated and error is undefined; on failure, data/publicData are empty and error is an Error.

FieldTypeDescription
isVerifiedbooleantrue when the proof (and content) is valid.
dataTrustedData[]One entry per proof: { context, extractedParameters } — the trusted, verified values. Empty [] on failure.
publicDataany[]The publicData from each proof (unverified). Empty [] on failure.
isTeeAttestationVerifiedboolean (optional)Present when a teeAttestation config was passed; true if the TEE attestation chain verified.
isAttestorTeeAttestationVerifiedboolean (optional)Whether the attestor's TEE attestation verified.
errorError | undefinedThe failure reason; undefined on success.

TeeAttestation

Present on a Proof when TEE attestation was requested at init.

FieldTypeDescription
proof_version'v2' | 'v3'TEE attestation version.
tee_providerstringThe TEE provider.
tee_technologystringThe TEE technology used.
noncestringAttestation nonce.
timestampstringWhen the attestation was produced.
workload{ container_name, image_digest }Identity of the workload container.
verifier{ container_name, image_digest }Identity of the verifier container.
attestation{ token }The attestation token.
error{ code, message } (optional)Present if attestation generation failed.

Structure of data POSTed to cancel callback

{
  "type": "string",
  "message": "string",
  [key: any]: any
}
Exception NameDescription
ReclaimVerificationCancelledExceptionVerification cancelled (likely another verification started or invalid request).
ReclaimVerificationDismissedExceptionVerification dismissed by user.
ReclaimAttestorExceptionException related to attestor.
ReclaimVerificationSkippedExceptionVerification skipped (proofs reused or manual review).
InvalidRequestReclaimExceptionRequest to start verification is invalid.
ReclaimVerificationPlatformNotSupportedExceptionPlatform not supported.
ReclaimVerificationOutdatedSDKExceptionInApp SDK version is outdated.
ReclaimVerificationManualReviewExceptionVerification submitted for manual review.
ReclaimVerificationProviderNotFoundExceptionProvider not found.
ReclaimVerificationAbortedExceptionVerification aborted by user (e.g. clicking cancel).
ReclaimVerificationProviderScriptExceptionProvider script reported an error.
ReclaimVerificationNoActivityDetectedExceptionNo activity detected.
ReclaimVerificationRequirementExceptionClaim creation requirements not met.
ReclaimVerificationProviderLoadExceptionProvider load failed.
ReclaimExpiredSessionExceptionSession expired.
ReclaimInitSessionExceptionError initializing session.

Description of RECLAIM_EXCEPTION in metadata

When the logType is RECLAIM_EXCEPTION, the metadata string parses to an object containing an exception field. The exception.type will be one of the following:

[!NOTE] In case of ReclaimVerificationProviderScriptException, the metadata may contain an additional providerError field with more detailed error information from the provider script. In case of ReclaimVerificationAbortedException, the metadata may contain an additional has_error boolean field which will be true if the user cancelled the verification after an error occurred during verification.

You can see some common reasons of failures here

On this page