Getting started

3 min read

Add Footprint.js to your app

  1. Go to the Footprint developer dashboard and create a new Onboarding configuration

    • Select the “standard” list of IDV fields to collect or customize the fields.
    • Select the “standard” list of IDV fields you require access to decrypt.
  2. Grab the Onboarding Publishable Key, for example ob_test_VMooXd04EUlnu3AvMYKjMW.

  3. Add the footprint.js script to your app.





# With NPM
npm install @onefootprint/footprint-js

# With yarn
yarn add @onefootprint/footprint-js
  1. Embed the Footprint button.


<div id="footprint-button" data-public-key="pk_test_yflLnFW219f9bC0pdyGd"></div>
  1. Add your Footprint completion handler


window.onFootprintCompleted = function (token) {
  // TODO: Post the token to your server
  1. To customize the button placement, the easiest way is to wrap the button in a div and apply the styles to this div:


  .container {
    display: flex;
    align-items: center;
    justify-content: center;
    height: 100vh;

<div class="container">

Click here to check out a full example.

Verify the Footprint token server-side

  1. Go to the Footprint developer dashboard and generate a new Secret API Key. This will look something like sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv. Add this to the credential manager of your server-side app.

The Footprint API uses API keys to authenticate requests. You can view and manage your API keys in the developer dashboard. Go to the Footprint developer dashboard and generate a new Secret API Key. Test mode secret keys have the prefix sk_test and live mode secret keys have the prefix sk_live.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value with no password. Alternatively, Footprint supports header-based auth via a custom header. If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "X-Footprint-Secret-Key: sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv" instead of -u <api_key>:.

  1. You should create an endpoint on your backend to handle signups. It should receive the validation token given in step 5 above from your frontend and pass it to Footprint’s backend in order to authenticate and verify the user:


curl -X POST \
   -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
   -d '{"validation_token": "vtok_udLaWUxPBo3fss603v8kY8k9ssjboxfwI"}'
  1. Footprint will give you some information from this onboarding session. We’ll also give you a footprint_user_id, which looks like fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX


  "data": {
    "footprint_user_id": "fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX",
    "status": "verified",
    "timestamp": "2022-07-30T05:39:33.723Z"
  1. Save the footprint_user_id in your database tied to the individual user. It is the identifier you will send to request any user-specific information.

  2. (Optionally) Fetch the user’s audit trail for detailed results on the identity verification:


curl -X GET -G \
   -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv:
  1. (Optionally) Decrypt identity fields from the user’s vault:


curl -X POST \
   -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
   -d '{"fields": ["dob", "last_name", "ssn4"], "reason": "getting started test"}'


  "dob": "1988-12-25",
  "last_name": "Smith",
  "ssn4": "1212"