Integration Guide
Introduction
Integration Process
The process of integrating Trinsic into your product requires three steps:
- Understand the User Journey
- Select and integrate a Session mode according to the aspects of the Journey you wish to control
- Test your integration
SDKs
We offer SDKs for a number of stacks, as well as samples, on our Github. We've included working samples for all SDKs which 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.
The User Journey
Providers Without a Journey
Some of the Providers within Trinsic's network are "lookup" or "match" Providers, whereby user information is validated and enriched against an authoritative database without requiring that the user be actively involved.
For these Providers, Trinsic offers hosted flows which guide the user through the process of submitting any necessary information (including a selfie for biometric matching if relevant). In these cases, Trinsic fully manages the User Journey.
If your product collects all necessary information from the user, it's possible to verify against these Providers without requiring any user journey beyond the initial collection of data within your product.
Any integration with Trinsic will ultimately guide the user through the three critical steps of a user verification journey: Provider Selection; Journey to the Provider; and Consenting to Share.
The first two steps of this process can be handled either by Trinsic or by your own product. The final step of the process occurs within the Identity Providers' products; Trinsic works with the Identity Providers on your behalf to configure the branding and configuration for this step.
Trinsic offers out-of-the-box support for each step, using our own User Interface to handle any required user interaction. If you wish to fully control the user experience, we also offer full OEM/API-only capabilities.
Provider Selection
The first step in verifying a user's digital identity is determining which digital identity provider or wallet they already have a shareable credential stored within.
With over 60 providers available in Trinsic's network, simply showing a list to the user and prompting them to make a selection quickly becomes an overwhelming user experience. Trinsic's Recommendation API exists to solve this problem: using signals and information about the user, we help you determine which Identity Providers a user is most likely to have a relationship with.
Alternatively, you can build your own user flow to select an Identity Provider.
Journey to the Provider
Once a user has selected an Identity Provider to verify with, they must be sent to the Provider's website, app, or other product experience. This can take a number of forms:
- A website which the user must be sent to in a browser
- An app installed on the user's device which must be invoked via a deep link
- A code which must be displayed to the user as they consent to the verification out-of-band
This step in the process is considerably fragmented across the digital identity landscape.
Trinsic can handle this step for you, using our customizable UI to handle any interactions more complex than a redirect. Alternatively, Trinsic's API enables you to fully handle this process in your own product, with no Trinsic UI required.
Consenting to Share
Once the user has arrived at the provider's website or app, they are presented with a consent screen containing information about the data being requested and the party requesting it.
Out of the box, Trinsic's branding is displayed on this consent screen for most Providers. Users are informed that "Trinsic" is the entity which is requesting their identity data.
To customize the branding displayed to the user, each Provider must be configured with the new branding in a Provider-specific way. Trinsic handles the vast majority of this on your behalf. We plan to offer an API-driven approach to manage this in the near future.
Sessions and Session Modes
To verify a user's digital identity, your backend calls our API to create a Session. Each Session encapsulates a single user's verification journey for a single verification.
Sessions can be created in one of three modes: Widget, Hosted, or Advanced, with different levels of flexibility and control over the user experience depending on your use case.
The following table lists the Session modes and details which aspects of the User Journey are handled by each party.
In Widget mode, Trinsic's UI handles both Provider Selection and the Journey to the Provider.
Use the Trinsic API to create a Widget session, then use our frontend SDKs to launch the Session using the launchUrl you receive.
Trinsic will guide the user through the process of selecting a relevant digital identity provider, and handle all user interaction required to perform the verification with said provider.
Choose Widget mode if:
- You are comfortable with Trinsic handling the UX end-to-end OR
- You want to integrate as quickly as possible
In Hosted mode, your UI handles the Provider Selection stage of the journey in whatever way you wish. Trinsic's UI handles any user interaction required (if any) for the Journey to the Provider.
Once the user has chosen a Provider, use the Trinsic API to create a Hosted session for said Provider. Send the user to the launchUrl you are given, and receive them back at your redirectUrl when they are done.
Trinsic UI is displayed only if necessary to complete the verification for the specific Provider.
Choose Hosted mode if:
- You wish to handle the Provider Selection step in your own UI AND
- You wish to use Trinsic's UIs to handle any user interaction required to get the user to the Provider's product
In Advanced mode, your UI handles both Provider Selection and the Journey to the Provider.
Once the user has chosen a Provider, use the Trinsic API to create an Advanced session for said Provider. We return all the data necessary to enable your own product to handle the required user interaction to send the user to the Provider's product experience.
Advanced mode is flexible and adapts to your integration's capabilities: optionally, Trinsic's UI can step in to handle any complex or niche user interactions which your product does not yet support, while allowing your product to handle any interactions it can.
Choose Advanced mode if:
- You wish to handle the Provider Selection step in your own UI AND
- You wish to handle some or all user interactions necessary to get the user to the chosen Provider in your own UI
Testing
To test your integration during and after development, Trinsic offers a rich set of mock test providers -- alongside access to the sandbox environment of live Identity Providers.
Trinsic Test Providers
Use Trinsic's mock test providers to perform a simulated digital identity verification flow through Trinsic's API with minimal friction.
These test providers are the smoothest way to test the integration between your product and Trinsic. We encourage you to use them when writing automated tests against your integration.
When using Advanced Sessions, Trinsic's test providers provide full coverage of the Advanced API, allowing you to implement full functionality without needing to use a live Identity Provider.
Test-Enabled Providers
Many live Identity Providers make available a test environment for their products, which we expose through our network whenever possible.
If a Provider supports test mode, it will appear in the list of available Providers for your test mode Apps. Provider-specific instructions for testing can be found in the documentation page for any specific test-enabled Provider.
Updated 11 days ago