ℹ️

Read First

We highly recommend reading the Integration Guide for an overview of the integration process, as well as the Direct Provider Sessions Overview page for context on this API.

Introduction

This document provides a quick guide on how to integrate Trinsic using the Create Direct Provider Session API.

In this mode, your product can manage the entire user experience and interface, with no Trinsic UI required at any point in the user journey.

Integration

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

1. List applicable providers

Display a list of identity providers to the user, prompting them to select one.

You can use the Recommend Providers 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 relevant providers.

Alternatively, you can use the List Identity Providers endpoint to simply list all providers.

Both endpoints return a logo and name; these must be shown exactly as provided to conform with brand requirements.

2. Create a Session

Once the user has selected an identity provider, call the Create Direct Provider Session method from your backend using an API SDK.

Provide the list of capabilities your application supports. We recommend starting with ["LaunchBrowser", "CaptureRedirect"] as a baseline (with fallback enabled) and building from there.

If you want Trinsic's UI to step in to fill in any gaps in your application's capabilities, set the fallbackToHostedUi field to true. You must then additionally always specify a redirectUrl and the LaunchBrowser and CaptureRedirect capabilities.

If you are launching a Provider which will return a CaptureRedirect Collection Method, you must specify redirectUrl.

Save the returned sessionId and resultsAccessKey in your database.

Sample Request and Response Payloads

{
	"verificationProfileId": "47d3b6cf-e93b-4ecd-a8c0-65013dc9f935",
  "capabilities": [
    "LaunchBrowser",
    "DeeplinkToMobile",
    "CaptureRedirect",
    "PollResult"
  ],
  "provider": "ca-mdl",
  "redirectUrl": "https://example.com/redirects/trinsic",
  "fallbackToHostedUI": true
}

{
  "sessionId": "67cb115f-ec42-48c1-9508-c0695996b971",
  "resultCollection": {
    "method": "PollResult",
    "resultsAccessKey": "38Kv8vrC3rm6vrb2RfhzDtrDnpFs8kfbKXXEiZ6oumyDt6muTfCtRfksGjdpcuYTkPRju87iqjsPpkyVGAWaf2yYEfGJa7f8W55RzBFkhr7wbVGqD4F9AmgLsPmuUaefptgAEHAJEjAB5Kbzr5dZ36UZQEYnLwgJrEzxYo52FUbw7h6UBV73Rma6HHySE7g9AF29rcNbRYg9YYac8ofoDR5jeTfFWbSoFdTk3hJZRJTSYfD2Ru9EpUtaCWBewHjSc1GY3otAU3DwAnRDgyuasM7uL4NQQff2bwAEA9V39Fh6xvFco28"
  },
  "nextStep": {
    "method": "DeeplinkToMobile",
    "content": "openid4vp://?client_id=did%3Aweb%3Aca-mdl.trinsic.id&request_uri=https%3A%2F%2Fca-mdl.trinsic.id%2Fworkflows%2Fz1Ca28JZPqBeAEcED50avWw2L%2Fexchanges%2Fz19mWDsEC93jhADwekJNLYK7V%2Fopenid%2Fclient%2Fauthorization%2Frequest"
  }
}

3. Handle nextStep

In the response to the API call you just performed, you received a nextStep object, which contains everything you need to launch the user into the verification flow.

nextStep.method is an enum describing the next step to perform.

nextStep.content is a string whose value is dependent on nextStep.method.

nextStep.refresh is an object which is non-null only if nextStep.content must be periodically refreshed.

If nextStep.method is LaunchBrowser

Launch the user's browser to the HTTPS URL stored in content.

You can do this by:

• Redirecting the user's browser window
  • Note: If resultCollection.method is not CaptureRedirect, you cannot rely on the user being redirected back to your application. In this case, may want to launch in a popup or new tab as opposed to a top-level redirect. This is an uncommon scenario, however.
• Opening a popup, new tab, or new window

If nextStep.method is DeeplinkToMobile

Launch the user's phone to the URI stored in content.

This URI contains a deep link which will launch a native app on the user's device, assuming they have the app installed.

To do this:

• If the user is on a desktop or laptop
  • Display the URI as a QR code and prompt the user to scan it OR
  • Display a QR code pointing to a page you control, which will display a button the user can tap on their phone to launch the URI
    • This is recommended if QR code size or complexity is a concern: some deep links can be very long URIs which introduce UX challenges when turned into a QR code.
• If the user is already on their phone
  • Display the URI as a button and prompt the user to tap it
    • Note: Automatically launching the URI without the user tapping it may cause reliability issues depending on the user's combination of OS, browser, and settings.

If nextStep.method is ShowContent

Display the content contained within nextStep.content to the user. Ideally, include instructions specific to the Provider being used.

There are two main interaction patterns covered by ShowContent:

1. Code Copying
   1. The user is shown a code which they must enter into an app or website in order to proceed with sharing.
2. Safety Code for Out-of-Band Communication
   1. The user is sent an out-of-band communication (e.g., a push notification on their phone or a text message) by the Identity Provider, prompting them to consent to sharing. The user verifies that the code displayed in their app is the same as the code displayed on your website.

If nextStep.method is PerformNativeChallenge

A native API, such as the Digital Credentials API on Web or the Android/iOS native app equivalent, must be executed.

Use one of Trinsic's client SDKs, passing in the content string to the performMdlExchange method. The output of this client SDK call is a string value, which you must pass back via the Submit Native Challenge Response method.

If you cannot or do not wish to use one of Trinsic's client SDKs, you must deserialize the content string and pass it into the browser or native app API call yourself. See our SDK source code for this simple operation.

Handling nextStep.refresh

If nextStep.refresh is non-null, then the value of nextStep.content is time-bound and will be rendered unusable after some time.

The value of nextStep.refreshAfter is a UTC date/time; Trinsic recommends you refresh the content at this time.

To refresh, call the Refresh Step Content API, passing in the resultsAccessKey contained in resultCollection.resultsAccessKey.

You must specify the RefreshStepContent capability during Session creation if you wish to support step refresh in your application.

4. Handle resultCollection

Alongside nextStep, the response to the Session creation call will contain a resultCollection object, which contains everything you need to collect the results of the Session.

resultCollection.method is an enum describing how you will retrieve the final results for the Session.

resultCollection.resultsAccessKey is a string which is required to collect the results of the Session.

If resultCollection.method is CaptureRedirect

The user will be redirected back to your application, at the redirectUrl you specified during Session creation. Trinsic will have appended the following query parameters:

• sessionId
  • The ID of the Session the user just completed
• resultsAccessKey
  • A string containing a key which can be used to access the Session results
    • Note: You also received a resultsAccessKey in response to Session creation, meaning you have two different resultsAccessKey strings available. Although these strings have different contents, there are no other differences: they are interchangeable.
    • By using the resultsAccessKey received upon redirect, you can validate that the user being redirected back is in fact the right user being sent by Trinsic, and not an impostor. An invalid resultsAccessKey cannot be used to fetch Session results, and Trinsic is the only entity capable of creating a valid resultsAccessKey. This adds a layer of authentication to the redirect boundary.
• postRedirectAction
  • A string with the possible values fetch and poll
  • If the value of this query parameter is fetch, the results of the Session are immediately available and can be fetched as soon as the user is redirected back to your application.
  • If the value of this query parameter is poll, the results of the Session are not immediately available; you must poll for the results via GetSessionResults until the Session concludes
    • This value will only appear if you specify the PollAfterRedirect capability during Session creation.

Extract the sessionId and resultsAccessKey from the query parameters.

Ensure that sessionId matches the Session you actually created for the user in question.

Use resultsAccessKey to retrieve Session results in step 5.

📘

Note

If you launched the verification in a popup, your backend will have to handle the redirect and send a message to the opening window to signal completion. Use our Web UI SDK's signalRedirectFromPopup() method to accomplish this, or build your own signaling mechanism.

If resultCollection.method is PollResult

The user will not be redirected back to your application after verifying themselves; you must poll for results in the background until they are available.

resultCollection.resultsAccessKey will contain the resultsAccessKey for the Session; store it in your database and use it to poll in step 5.

If resultCollection.method is SubmitNativeChallengeResponse

You must submit the output of the native API call you performed in step 3 to the Submit Native Challenge Response API.

If you are using a Trinsic client SDK, this simply requires sending a string from your client to your backend.

If you cannot or do not wish to use a Trinsic client SDK, you must serialize the response object into a string in the format our API expects. See our SDK source code for this simple operation.

5. Retrieve Session Results

📘

Note

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

If you discard it, you won't be able to access the Session results.

Once you have a resultsAccessKey, call the Get Session Results API to retrieve the results of the Session.

If results are not yet available, this API will return a Session object with both done and success set to false. This could happen if:

• resultCollection.method is PollResult, and the user has not finished the verification yet
• resultCollection.method is CaptureRedirect, and the identity provider is still processing the results
  • See the PollAfterRedirect capability

Test Providers

We offer a number of test providers, each of which covers a different set of capabilities:

• Test - Redirect
• Test - DeeplinkToMobile
• Test - DeeplinkToMobile + RefreshStepContent
• Test - ShowContent
• Test - ShowContent + RefreshStepContent
• Test - Database Lookup
• Test - Sub-providers