Integration flow

Requirements

To integrate Trinsic, you will need a secure backend (from which you will make API calls) and a frontend (website or mobile app).

0. Optionally list applicable providers

You can use our Recommend Providers (Experimental) endpoint to recommend the most applicable providers to your user. We will search our network and using signals such as region, phone number and your app settings recommend a list of providers. Otherwise you can use the List Identity Providers endpoint for listing all providers. Both endpoints return a logo and name that are required to be shown exactly as specified to retain brand identities.

1. Create a Session

When you're ready to verify a user, call the Create Session method from your backend using an API SDK. If you want to launch a user into a direct mode session (launching a specific provider directly) you set the launchProviderDirectly boolean to true and add a single, specific provider, to the providers list.

The response to this call will include a Session id and launchUrl.

Save the id somewhere in your database; send the launchUrl to your frontend (web / mobile app).

2. Launch Session on Frontend

Once your frontend has received the launchUrl from your backend, use a UI SDK to launch the Session.

Depending on the environment, the LaunchSession SDK call may be implemented using an async/await pattern that blocks until results are available, or may be a synchronous call which returns immediately and sends results via a registered callback.

The results of the LaunchSession call on your frontend will contain a resultsAccessKey if the Session completed successfully. If the Session did not complete successfully, resultsAccessKey will not be provided, and additional fields (e.g. canceled) provide further information.

Once you have a resultsAccessKey (or a failed result with no key), send it to your backend:

• If resultsAccessKey is present, send it to your backend
• If resultsAccessKey is not present, send a message to your backend indicating that the Session did not complete successfully

3. Retrieve Session Results

📘

Note

The resultsAccessKey is required in order to retrieve sensitive identity data from a Session.

Once your frontend has sent the resultsAccessKey to your backend, use an API SDK to retrieve the results:

• If the Session was successful and your frontend sent a resultsAccessKey, call the Get Session Results endpoint
• If the Session was not successful, call the Get Session endpoint
  • This will allow you to inspect the Session's state and (if applicable) failure reason, as described in Handling Errors.

4. (Optional) Redact Session

Trinsic automatically redacts all Sessions after a specified redaction period, which can be configured on a per-Application basis in the Dashboard .

If you would like to redact a Session's identity data before the specified redaction period, call the Redact Session endpoint from your backend.

We recommend that you redact Sessions immediately after consumption of their results.

Launching Verification Sessions

There are two ways to launch a verification session.

• Prebuilt Workflow - A low-code, branded verification session that can be set up in the dashboard and launched with a button or via an API. This method requires you to build 2 backend calls, one to create a session and one to send the resultsAccessKey to. You can launch the prebuilt workflow as an embedded iframe or as a Trinsic-hosted webpage via redirect or popup.
• Launch Providers Directly - For scenarios that require more customization, a specific ID Provider can be directly launched as a button within your existing verification journey (eg CA DMV Wallet), with minimal Trinsic-specific UI. With this method, you'll need to build a method to list the available providers that you want a user to see.

Test ID Provider

You can choose to enable a test ID provider (by default enabled) for easy testing. It will allow you to quickly go through an identity validation without needing to use an actual digital ID. The Test ID Provider is only meant to be used for demonstrations, development, and testing and will be disabled when the "Enable all integrations" button is toggled, as that is intended for production deployments.

Launch options

Mobile

On mobile we provide SDKs to securely launch and handle the result of our sessions. We use the underlying operating systems capabilities, such as ASWebAuthenticatorSession on iOS and ChromeCustomTabs on Android to provide a seamless experience to launch a session and capture the result.

Web

On the web we provide 3 launch options:

iFrame

This mode is available if you run the full flow but not if you launch a direct flow as browsers limit cookie storage options for iFrame's that we bypass in the full flow by handing the user over to another device or tab.

We layover a gray transparent background over your site and present the user with our Widget on top of all your content.

Popup

This mode is available for both the full flow and the direct flow and simply launches a browser popup that guides a user through their respective verifications.

Redirect

We simply redirect the user to our launch URL when you use our SDK, you can also trigger this from your own backend. You will have to handle the resultsAccessKey from the return url query parameters. A return url is required for this mode to launch.

SDKs

You can find all our SDKs including samples on our Github. We've included working samples for all SDKs that require only your auth token to run. If your specific tech stack isn't covered, please let us know; we're happy to help you get started. Click each link to find a detailed readme on the SDK's specific usage.