Introduction

ℹ️

More Information

We highly recommend reading the Advanced Provider Sessions Overview page for context on this API.

This document provides a quick guide on how to integrate Trinsic using the Create Advanced 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 Advanced 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 in your database.

Sample Request and Response Payloads

{
  "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.

You can do this by:

• If the user is on a desktop or laptop
  • Displaying the URI as a QR code and prompt the user to scan it
• If the user is already on their phone
  • Displaying the URI as a button and prompt the user to tap it
  • 
    

Handling nextStep.refresh

If nextStep.refresh is non-null, then the deep link 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 deep link 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 only set if resultCollection.method is PollResult.

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

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.

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.

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 204 No Content response. This could happen if:

• resultCollection.method is PollResult, and the user has not finished the verification yet
• The Identity Provider has not yet made the results available, and they must be polled for
  • This can occur even if resultCollection.method is CaptureRedirect