Quickstart

Add OpenPassport verification your app.

Web app

Installation

Simply run the following command to install sdk.

# npm
npm install @openpassport/sdk

# yarn
yarn add @openpassport/sdk

Import

import OpenPassportQRcode from OpenPassport sdk.

import { OpenPassportQRcode } from '@openpassport/sdk';

Instantiate QR code component

Simply instantiate QR code component like in this example:

<OpenPassportQRcode
    appName="🚀 Space Explorer"
    scope="@space_explorer"
    userId={userID}
    requirements={[["nationality", "France"], ["older_than", "18"]]}
    onSuccess={handleSuccessfulVerification}
    devMode={false}
    size={300}
 />

Learn here about how OpenPassport QR codes are generated and behave.

OpenPassportQRCode parameters

parameter	Optional	Description	Default	type
appName	M	name of the app, will be displayed in OpenPassport UI		string
scope	M	unique identifier of the application		string
userId	M	user identifier, UUID is recommended		string
userIdType	O		uuid	ascii | hex | uuid
requirements	O	optional requirements needed to pass the verification		string
onSuccess	M	callback function called at proof verification, only if the proof is valid		(proof , report) => void
devMode	O	if activated, allows user with a computer generated passport to verify their proof	false	boolean
size	O	size of the QR code	300	number
websocketUrl	O	address of the WSS	wss.openpassport.app

userId

Open passport allows 3 types for userId field

• uuid

• hex

• ascii (extended_ascii)

userId is passed as a public signal during the proof generation to avoid any possibility of front running attacks, making impossible to steal the proof of someone else.

OpenPassport is using BN254 curve for ZK-SNARKS generation, capping the max bit value of any inputs to 253 bits. This impact the userId length according to userId type.

uuId type	max lenght
uuid	static
hexa	63
ascii (extended_ascii)	25

Handle Proof Verification

You can use OpenPassport1StepInputs injected in the callback method to retrieve users userId or nullifier and execute a specific action.

UserId

User identifier can be retrieved from the verificationResult

// for UUID parsing
const userId = proof.getUserId();

Verify proof in the backend

Once the proof verified in the web browser, you have to send it and verify it to your backend server.

const handleSuccessfulVerification = async (proof: OpenPassport1StepInputs, verificationResult: OpenPassportVerifierReport) => {
            const response = await fetch('<your_endpoint>/api/verify', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({ proof: proof}),
            });
            if (response.status === 200) {
                const data = await response.json();
                console.log('Backend verification result:', data);
            } else {
                throw new Error('Failed to verify proof');
            }
    };

Finally use OpenPassport1StepVerifier to verify the proof

import { OpenPassport1StepInputs, OpenPassport1StepVerifier } from '@openpassport/sdk';

const verifierArgs = { scope: scope, requirements: [["older_than", olderThan], ["nationality", nationality]], dev_mode: true } }
const openPassport1StepVerifier = new OpenPassport1StepVerifier(verifierArgs);
const isValid = (await openPassport1StepVerifier.verify(proof as OpenPassport1StepInputs)).valid;

Nullifiers

A nullifier is a unique and deterministic identifier generated for each user. OpenPassport nullifier are generated by hashing the signature of the passport with the scope of the application.

To avoid users from using the same passport between multiples accounts, you just have to store them and verify that they don't have already been used.

const nullifier = proof.getNullifier();
// check that nullifier has not already been used and store it

Mobile app

Mobile application integration through deep linking is under development. Please reach us if you need it.