Implementation (Terra widget)

1. Make an API Request

Make an API Request to the /auth/generateWidgetSession endpoint from your backend.

Command Line
curl --request POST --url https://api.tryterra.co/v2/auth/generateWidgetSession \
  --header 'dev-id: <YOUR-DEV-ID>' \
  --header 'x-api-key: <YOUR-API-KEY> \
  --header 'Content-Type: application/json' \
  --data '{
      "language": "en",
      "reference_id": "my_first_connection",
      "auth_success_redirect_url": "text",
      "auth_failure_redirect_url": "text",
  }'

Pro tip: Use reference_id in your request Body to pass in your own end user's ID on your system.

This will simplify reconciling the Terra User with your end user.


2. Parse the Widget URL from the JSON Response

The endpoint will generate a widget url in the response. Retrieve it by parsing "url" .

JSON
{
   "session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
   "url": "https://widget.tryterra.co/session/344d475f-296a-489a-a88c-54183671dafd",
   "status": "success",
   "expires_in": 900
}

3. Open The Widget URL

Pass the retrieved "url" to your client side, and open it either in:

  • an in-app browser, if using a mobile app,

  • or a new tab, if using a web app

This will take your end user to the provider selection screen, the Terra authentication widget.

Device Selection screen (Terra authentication widget)
Login Screen (example: Oura)
Permission screen (example: Oura)

The permissions list can be customised through your Terra Dashboard

You can find a list of all your authenticated users in:


❌ Common Mistakes

Common Mistakes and Best Practices

Last updated

Was this helpful?