Getting started

3 min read

Setup and authentication

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>:.

Sanity check

You can check that your API key is working as expected:

bash

curl https://api.onefootprint.com/org/api_keys/check \
    -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv:

Create a user vault

The first step is to create a new vault for one of your users:

bash

curl https://api.onefootprint.com/users \
    -X POST \
    -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv:

json

{
  "footprint_user_id": "fp_id_K0q6Eh6Rr3WOOfFBLPiHsr",
  "start_timestamp": "2022-08-26T14:05:35.200031Z",
  "is_portable": false
}

Save this footprint_user_id, associate it with the corresponding user in your database.

Update a user vault

Footprint user vaults store two types of data attributes: structured and unstructured. Structured data are first-class attributes that Footprint automatically validates, tokenizes, and in some cases fingerprints to make searchable. Unstructured data are custom key-value attributes that are provided by you and are not validated. Unstructured data are keyed by the format: custom.<key> in Footprint’s API requests.

bash

curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault \
    -X PUT \
    -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
    -d '{ "identity": {
                "name": {
                    "first_name": "John",
                    "last_name": "Smith"
                },
                "dob": {
                    "day": 12,
                    "month": 12,
                    "year": 1988
                },
                "ssn9": "12-121-1212"
             },
            "custom": {
                "ach_account": "111122224444",
                "cc4": "4242"
            }
        }'

List available data in a user's vault

Check what fields exist on a user's vault.

bash

curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault?fields=identity.ssn9,custom.ach_account \
      -u sk_test_CJvsN1kaZH3GGtYkaZH3GGtY:

json

{
  "identity": {
    "ssn9": true
  },
  "custom": {
    "ach_account": true
  }
}

Decrypt data from a user's vault

Footprint’s API provides attribute-level decryption. API keys are configurable to have certain attribute-level scopes.

bash

curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault/decrypt \
    -X POST \
    -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
    -d '{
            "fields": ["identity.last_name", "identity.dob", "identity.ssn9", "custom.ach_account"],
            "reason": "direct deposit verification"
        }'

json

{
  "identity": {
    "last_name": "Smith"
    "dob": "1988-12-25",
    "ssn9": "121211212",
  },
  "custom": {
    "ach_account": "111122224444"
  }
}

Search across users' vaults

Footprint lets you search across all of your users' vaults by specific fields that are fingerprinted. This lets you easily search across all of your users vaults privately without building complicated decryption procedures.

bash

curl -X POST https://api.onefootprint.com/users?fingerprint=10014 \
      -u sk_test_CJvsN1kaZH3GGtYkaZH3GGtY:

json

{
  "data": [
    {
      "footprint_user_id": "fp_id_XyEJ6CF7UNl6K2ymIq8YQS",
      "start_timestamp": "2022-08-26T17:19:55.048883Z",
      "is_portable": false
    }
  ],
  "meta": {
    "next": null,
    "count": 1
  }
}