Legacy widget (generateWidgetSession)

Deprecation notice. This endpoint is deprecated. Planned deprecation date: 3 November 2026.

For existing integrations, POST /auth/generateWidgetSession keeps working today, and we will give notice well before any breaking change. Plan to migrate before the deprecation date: it takes a few minutes, and the migration notes on Implementation (Terra widget) cover the differences.

Terra accounts created after 3 September 2026 cannot use this endpoint. Calls return a 410 error pointing to the replacement, POST https://access.tryterra.co/api/widget/session.

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:

• Your Terra Dashboard > Users

• Or by using the /subscriptions endpoints

---

❌ Common Mistakes

Common Mistakes and Best Practices

• Do not expose your API credentials. Instead, always call the /auth endpoints from your backend.

• Do not call the API from your frontend, as this will lead to a CORS error.

• Do not use WebView or iFrame for the authentication flow. Using them poses security risks due to the invisible URL bar, meaning that the user cannot know the domain onto which they are entering their username & password. Providers may completely block authentication leading to an error during the flow. Instead, use a new tab or an in-app browser to open the URL returned by the /auth endpoints.