User-specific sessions

When a user has already identified themselves to your app, open the Footprint SDK with an auth token specific to that user. You collect new and updated information from an existing user over time, and the user cannot create a second Footprint account when they already have one linked to your app.

Use it to:

• Onboard the user onto a playbook.
• Ask the user for a new driver's license when theirs expires.
• Collect information you requested from the Footprint dashboard.
• Let the user update their login methods with Footprint.

You call the API with your secret API key; see Server-side API authentication.

Store a mapping from your own user records to the user's Footprint identifier, the fp_id. When the user logs in to your app, look up the fp_id of the user you want to open the flow for.

If the user has no fp_id yet, create one in Footprint and vault the information you have already collected; Migrating user data shows how.

The flow does not ask the user again for data already in their vault, though they can edit it.

From your backend, with your secret API key, generate an auth token for the user with the POST /onboarding/session API:

bash
1curl https://api.onefootprint.com/users/fp_id_K0q6Eh6Rr3WOOfFBLPiHsr/token \
2  -X POST \
3  -d '{"kind": "onboard", "key": "pb_live_qBV2iO3nQI5moqo5GJlFhI"}' \
4  -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv:

The response carries the token and its expiry:

json
1{
2  "token": "utok_vJK5Ze2N5fQ1GtE5V770BH8CZtQwXHF1hxowB9Nowh0",
3  "expires_at": "2023-10-24T20:44:13.639341Z"
4}

Choose the token kind that matches the SDK component you use and the flow you launch the user into.

Some token kinds take additional options, described below.

From the Footprint dashboard, you can request additional information from a user who has already onboarded, such as an SSN card or a driver's license. By default, Footprint sends the user a link to complete the form. To keep the user in your app instead, embed the Footprint Verify component with an inherit token and it completes any outstanding data requests.

Before you generate the token, check whether the user has an outstanding request with the GET /users/{fp_id} API:

bash
1curl https://api.onefootprint.com/users/fp_id_K0q6Eh6Rr3WOOfFBLPiHsr \
2  -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv:

A user with an open request looks like this:

json
1{
2  "id": "fp_id_K0q6Eh6Rr3WOOfFBLPiHsr",
3  "requires_manual_review": false,
4  "status": "pass",
5  "requires_additional_info": {
6    "timestamp": "2023-12-12T21:28:38.771377Z",
7    "note": "Hi Christian, we can't wait for you to get started with your Acme Bank credit card! To finish verifying your identity, can you please submit a photo of your SSN card? Once received, we can approve your application and mail out your credit card."
8  }
9}

A non-null requires_additional_info means there is an outstanding request for this user, and you can create an inherit token. It also carries the human-readable note you wrote in the dashboard for the user, which you can render in your own app.

An update_auth_methods token lets the user update their login methods through the Footprint Auth component. The user first logs in with an existing login method on their account, then can update their phone, their email, or both.

To limit which auth methods the user can update, pass the allowed methods in limit_auth_methods when you create the token. For example, to let the user update only their phone number:

bash
1curl https://api.onefootprint.com/users/fp_id_K0q6Eh6Rr3WOOfFBLPiHsr/token \
2  -X POST \
3  -d '{"kind": "update_auth_methods", "limit_auth_methods": ["phone"]}' \
4  -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv:

Pass the auth token to the Footprint SDK. The SDK asks the user to authenticate, then launches the flow the token kind or playbook specifies. The token kinds table says which component to invoke; the page for your SDK covers the platform specifics.

For a KYC (Know Your Customer) onboarding, pass authToken as a prop:

javascript
1import "@onefootprint/footprint-js/dist/footprint-js.css";
2import footprint from "@onefootprint/footprint-js";
3
4const handleClick = () => {
5  const component = footprint.init({
6    kind: "verify",
7    authToken: "utok_vJK5Ze2N5fQ1GtE5V770BH8CZtQwXHF1hxowB9Nowh0", // Auth token from Step 2
8    onComplete: (validationToken) => {
9      // TODO: Post to Footprint server to fetch user ID or verification status
10    },
11  });
12  component.render();
13};

For the update auth methods flow, pass authToken the same way:

javascript
1import "@onefootprint/footprint-js/dist/footprint-js.css";
2import footprint from "@onefootprint/footprint-js";
3
4const handleClick = () => {
5  const component = footprint.init({
6    kind: "update_login_methods",
7    authToken: "utok_vJK5Ze2N5fQ1GtE5V770BH8CZtQwXHF1hxowB9Nowh0",
8    onComplete: (validationToken) => {
9      // TODO: Post to Footprint server to fetch user ID or verification status
10    },
11  });
12  component.render();
13};