Quickstart

This is the simplest version of creating a proof request.

Import the library

import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk';

Setup a request on the backend

const reclaimProofRequest = await ReclaimProofRequest.init(
    'APP_ID',
    'APP_SECRET',
    'PROVIDER_ID'
)

• You can get the APP_ID and APP_SECRET using this guide
• The PROVIDER_ID is the proof you want the user to generate. You can see all the available providers here.

Send back the proof request object to the frontend

const proofRequestObject = reclaimProofRequest.toJsonString();

Sample implementation in Next.js

import { NextResponse } from 'next/server';
import { ReclaimProofRequest } from '@reclaimprotocol/js-sdk';
 
export async function GET(request) {
  let providerId = 'example';
 
  // add logic to choose provider id here based on request
 
  proofRequestOptions = {
    ..., //other options, if any
    useAppClip: false,
    customSharePageUrl: 'https://portal.reclaimprotocol.org'
  }
 
  // Initialize SDK with server-side environment variables (secure)
  // and request options
  const reclaimProofRequest = await ReclaimProofRequest.init(      
      process.env.RECLAIM_APP_ID,
      process.env.RECLAIM_APP_SECRET,
      providerId,
      proofRequestOptions);
 
  // Convert to JSON string (safe for frontend)
  const proofRequestObject = reclaimProofRequest.toJsonString();
 
  return NextResponse.json({
      success: true,
      proofRequest: proofRequestObject
  });
}

Advance Options

We recommend most, if not all of the following to be set for most production usecases :

Set Context

Set Address & Message as context

You can set context to the proof request that helps identify the request when you receive it back in the callback once the proof is generated.

reclaimProofRequest.setContext('address', 'message')

• address : this is usually a unique identifier for the user. This could be an email address, a wallet address, or just a session id generated on your system
• message : this is an open field where you can add any other information that you want passed around from the build request to the callback endpoint. You can stringify jsons here for convenience.

Set JSON Context

A JSON serializable object can also be set as context. For doing this, use setJsonContext method.

reclaimProofRequest.setJsonContext({
  address: 'hello@example.org',
  sessionId: '123'
})

[!WARNING] Both setContext and setJsonContext overwrite each other. Each call replaces the existing context.

Set Callback URLs

Success Callback

reclaimProofRequest.setAppCallbackUrl(url, jsonProofResponse)

Set a backend callback URL where Reclaim Protocol will send proofs directly after verification. In this case proofs are sent only to the custom URL instead of the Reclaim backend. This enables secure backend proof processing without relying on your frontend to upload the proof.

This verification session's id will also be present in X-Reclaim-Session-Id header of the request.

By default, proofs are sent as HTTP POST with Content-Type as application/x-www-form-urlencoded. Pass function argument jsonProofResponse as true to send proofs with Content-Type as application/json.

You can see the data structure of the proofs you will receive here.

[!Note] If you are using reclaimProofRequest.startSession after setting a custom success callback URL, then the proofs will be sent to the custom URL instead of the Reclaim backend. Because of this, the startSession onSuccess callback will be invoked with an empty array ([]) instead of the proof data, as the proof is not available to the SDK in this flow.

Cancel Callback

The easiest way to handle cancellations by user is to set up a cancel callback. This allows your application to react immediately when a user's verification session terminates.

reclaimProofRequest.setCancelCallbackUrl("https://yourwebsite.com/reclaim-cancelcallback"); // POST request webpage

If the user cancels the session midway or after error, Reclaim will send a POST request to you on the cancel callback URL with details. This verification session's id will be present in X-Reclaim-Session-Id header of the request.

Following is the data format which is sent as an HTTP POST request to the url with Content-Type: application/json:

{
  "type": "string", // Name of the exception are in the table below
  "message": "string",
  "sessionId": "string",
  // context as canonicalized json string
  "context": "string",
  // Other fields with more details about error may be present
  // [key: any]: any
}

What triggers cancel callback?

Following are some exceptions that happen when user presses a button to cancel in UI or provider custom injection script causes a cancellation by calling Reclaim.reportProviderError in browser.

Other errors (such as network timeouts or internal exceptions) may also trigger this callback if auto submit is enabled. In any case, you can always find the complete list of errors by fetching analytics events for the session.

[!TIP] Best Practice: When using setAppCallbackUrl and/or setCancelCallbackUrl, your backend receives the proof or cancellation details directly. We recommend your backend notifies the frontend (e.g. via WebSockets, SSE, or polling) to stop the verification process and handle the appropriate success/failure action. Do not rely completely on startSession callbacks on the frontend when using these backend callbacks.

Redirect after proof generation or cancellation

Success Redirect URL

If you want to redirect the user after generating the proof to a specific webpage or app, you can do so using setRedirectUrl.

When you should use this:

• User is on a desktop, scans QR code to generate the proof. After the proof generation is complete you want to show a custom success message on their mobile device instead of the Reclaim Protocol's default success message. You can redirect them to a webpage.
• User is on a mobile, taps a button to generate the proof. After the proof generation is complete, you typically want to redirect the user to the page that must be shown after the proof generation is complete. If you are using onSuccess, the user will have to close the proof generation success banner and go back to the browser to continue. We recommend using a redirect url to take the user to the next step in the business logic. On this step, render a page depending on whether the proof was correctly verified.

// Redirect to success page after verification
reclaimProofRequest.setRedirectUrl("https://yourapp.com/verification/success");
 
// Or deep link back to a mobile app
reclaimProofRequest.setRedirectUrl("yourapp://verification-complete");

Redirection with body:

• url: The URL where users should be redirected after successful proof generation.
• method (optional): The redirection method to use. Allowed options: GET (default) and POST. Note: POST form redirection is only supported in In-Browser SDK.
• body (optional): List of name-value pairs to be sent as the body of the form request.
  • When method is POST, body is sent with application/x-www-form-urlencoded content type.
  • When method is GET, if body is set, it is sent as query parameters. Note: Sending body on redirection is only supported in In-Browser SDK.

reclaimProofRequest.setRedirectUrl(
  "https://example.com/redirect",
  "POST", // In-Browser SDK only
  [{ name: "foo", value: "bar" }]  // In-Browser SDK only
);

Redirection happens after success callback is invoked by reclaim.

Cancel Redirect Url

Set a custom URL to redirect users when their verification process is cancelled. This allows your application to react immediately when a user's verification session terminates.

reclaimProofRequest.setCancelRedirectUrl("https://example.com/cancel-redirect");

Redirection with body:

• url: The URL where users should be redirected after an error which aborts the verification process.
• method (optional): The redirection method to use. Allowed options: GET (default) and POST. Note: POST form redirection is only supported in In-Browser SDK.
• body (optional): List of name-value pairs to be sent as the body of the form request.
  • When method is POST, body is sent with application/x-www-form-urlencoded content type.
  • When method is GET, if body is set, it is sent as query parameters. Note: Sending body on redirection is only supported in In-Browser SDK.

reclaimProofRequest.setCancelRedirectUrl(
  "https://example.com/error-redirect",
  "POST",  // In-Browser SDK only
  [{ name: "error_code", value: "1001" }]  // In-Browser SDK only
);

Redirection happens after cancel callback is invoked by reclaim. See What triggers a Cancel Callback for more details.

Set Parameters

If you already know what the value of the extracted parameter is supposed to be, you can set that using setParams. For example, if you know that the user's name before hand - and you want them to prove something from a website and you need the name to match exactly, you should use set the name in the params. Be sure to use the same key as the parameter name on the Provider you are using.

If the extracted parameter doesn't match the set parameter, the proof generation will fail.

reclaimProofRequest.setParams({ 
    name : "John Doe"
})

Add additional metadata for verification client

Additional metadata to pass to the verification client. This can be used to customize the client experience, such as customizing themes or UI by passing context-specific information. The keys and values must be strings. For most clients, this is not required and goes unused.

// Initialize with options
const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, {
  metadata: { theme: 'dark' },
});

Set preferred locale for verification client

You can change the language for the UI seen by User during verification by setting the preferredLocale parameter in the initialization options.

This is used to select a user's language and formatting preferences in the verification journey.

The value of this field must be a Unicode Language Identifier (i.e. without Locale extensions), except variants are not supported. Locale values are expected to be canonicalized according to the "preferred value" entries in the IANA Language Subtag Registry. For example, he, and iw are equal and both have the languageCode he, because iw is a deprecated language subtag that was replaced by the subtag he.

Defaults to the browser's locale if available, otherwise English (en).

// Initialize with options
const proofRequest = await ReclaimProofRequest.init(APP_ID, APP_SECRET, PROVIDER_ID, {
  preferredLocale: 'en-US',
});

Using the in-browser SDK

If you don't want to use the in-browser SDK, the users will be asked to install the Reclaim Protocol App/Appclip. You can disable by removing this configuration from the above snipped :

//REMOVE :
proofRequestOptions = {
    ..., //other options, if any
    useAppClip: false,
    customSharePageUrl: 'https://portal.reclaimprotocol.org'
}
const proofRequest = await ReclaimProofRequest.init(appId, appSecret, providerId, proofRequestOptions);

See reference implementation