Overview

Introduction

Trinsic's digital identity platform aggregates access to a wide range of Identity Providers, many of which require unique integration efforts. While some identity providers offer simple redirect-based browser flows, others require bespoke user interaction, such as: displaying a QR code or button; invoking JavaScript; displaying special instructions; or prompting the user to provide input or take a picture.

These unique user interactions and flows are fully handled by Trinsic when you make use of our Widget or Hosted Provider Sessions; simply integrate Trinsic's API and let us handle the rest. However, this necessarily means that Trinsic's UI is displayed to users when required.

If your use-case requires full control over the user interface, the Advanced Provider Sessions API is the tool for the job.

Features

The Advanced Provider Sessions API:

Allows your product to completely own the user interface and experience
Responds dynamically to your integration's capabilities, with optional "fallback-to-Trinsic" functionality
- You tell our API which kinds of user interactions your interface can support
- Optionally, Trinsic's UI can step in to fill any gaps in your integration's capabilities

Key Concepts

`LaunchMethod` and `CollectionMethod`

The Advanced Provider Session API provides a simple, powerful abstraction over the wide variety of flows and integration methods that the Identity Providers in Trinsic's network employ. To do this, we break the various flows apart into their constituent, categorizable, Launch Methods and Collection Methods.

Launch Methods

A LaunchMethod is the method by which a user must be launched into their verification flow.

Launch Method	Description	Refresh
`LaunchBrowser`	Send the user's browser (via redirect, popup, or new tab) to the given URL. User can be on desktop or mobile phone.	No
`DeeplinkToMobile`	Launch the given URI on the user's mobile device. If the user is on desktop, display the URI as a QR code for them to scan. If the user is on mobile already, display the URI as a button for them to tap.	Maybe
`ShowContent`	Display a piece of content (such as a 4-digit code), which the user will use to launch themselves into the verification, e.g. by launching an app and typing in the code.	Maybe
`None`	No action must be taken to launch the user. Simply collect the results. This may be returned if: - The given provider is a database lookup as opposed to a user-based data sharing flow - The identity provider will launch the session with the user via an alternative channel, such as a push notification or SMS	No

Refreshable Content

Certain Launch Methods have accompanying content which may need to be refreshed, depending on the needs of the specific Provider.

For example, the samsung-wallet Provider uses a DeeplinkToMobile Launch Method, with a deep link which expires after 30 seconds. This deep link must be refreshed periodically to prevent it from going stale.

Trinsic's API makes it simple to implement this refresh functionality.

Collection Methods

A CollectionMethod is the method by which you must collect the results of a Session.

Collection Method	Description
`CaptureRedirect`	The user will be redirected back to your specified `redirectUrl` with a `resultsAccessKey` in the query parameters. Call the `GetSessionResults` API with the `resultsAccessKey`.
`PollResult`	The `resultsAccessKey` is provided immediately in the Session creation response. Poll the `GetSessionResults` API with the `resultsAccessKey` until results are available.

Capabilities

Capabilities are how you signal to Trinsic which aspects of the user experience your application is capable of handling. Specifically, most capabilities correspond to a LaunchMethod or CollectionMethod, indicating whether or not your application is able to handle the respective method.

Capabilities are specified during Session creation, and are one of the primary mechanisms by which Trinsic determines whether or not to invoke the Hosted UI fallback.

List of Capabilities

Capability	Description
`LaunchBrowser`	Your application supports the `LaunchBrowser` Launch Method.
`DeeplinkToMobile`	Your application supports the `DeeplinkToMobile` Launch Method.
`ShowContent`	Your application supports the `ShowContent` Launch Method.
`CaptureRedirect`	Your application supports the `CaptureRedirect` Collection Method.
`PollResult`	Your application supports the `PollResult` Collection Method.
`RefreshStepContent`	Your application supports `nextStep` content which must be refreshed periodically. For example, some Providers utilize deeplinks which have a short time-to-live, and which must be refreshed periodically.

Provider-Specific Input

Some Identity Providers require that certain input be collected from the user before verification can proceed. This input must be collected by Trinsic or by your application. Examples of input include: an image of the user's face; self-attested identity information from the user; an email or phone number identifying the user to the Provider.

When using the Widget or Hosted Provider APIs, Trinsic's hosted UI manages the process of collecting this input from the user.

When using the Advanced Provider API, you may either collect this input yourself and pass it to Trinsic during Session creation, or allow Trinsic to collect it with our hosted UI fallback described below.

Hosted UI Fallback

Optionally, Trinsic's Hosted UI can step in to fill any gaps in your application's capabilities.

Fallback is configured on a per-Session basis, via the fallbackToHostedUi boolean during Session creation. If set to true, fallback is enabled and will occur if necessary. If set to false, fallback will not occur, and errors will be raised on Session creation if your application lacks a necessary capability or input.

If fallback occurs, the LaunchMethod and CaptureMethod for a Session will always be LaunchBrowser and CaptureRedirect respectively.

Capability Fallback

If a Provider requires a capability which you do not claim to support, fallback will occur, invoking Trinsic's UI to fulfill the user interaction requirements for said Provider.

For example, if a Provider requires the DeeplinkToMobile and PollResult capabilities, but you only specified ["LaunchBrowser", "DeeplinkToMobile", "CaptureRedirect"] during Session creation, then Trinsic must fall back to its hosted UI in order to perform the polling which is required for the given flow.

Input Fallback

If a Provider requires a piece of input which you did not provide during Session creation, fallback will occur, invoking Trinsic's UI to collect the necessary input from the user.

For example, if a Provider requires an image of the user's face to perform biometric matching, but you did not provide one during Session creation, then Trinsic must fall back to its hosted UI in order to collect the image from the user.

Examples

Below are some examples of specific Providers and how they are integrated into the Advanced Provider Session API.

CLEAR

Launch Method: LaunchBrowser
Collection Method: CaptureRedirect
Special UI: No

CLEAR is a web-based redirect flow. Users are sent to the CLEAR website, where they authenticate, consent to sharing data, and are finally redirected back.

Because CLEAR is a simple redirect flow with no special user interaction, no special integration effort or UI is required.

California DMV mDL

Launch Method: DeeplinkToMobile
Collection Method: PollResults
Special UI: Yes, to display QR code and/or button, and to poll for the results to be available

California DMV is an app-based "pull" flow. By scanning a QR code or tapping a link on their phone, users open their CA DMV mobile app, consent to sharing data, and are told to return to where they were.

Because the user is not redirected anywhere when the verification is complete, there is no "trigger" alerting the end of the session. Therefore, the results must be polled for asynchronously.