For the complete documentation index, see llms.txt. This page is also available as Markdown.

Terra authentication widget

Create a widget session from your backend and send the end user to the hosted screen where they pick a provider and log in.

The Terra widget is a hosted screen where your end user picks their data provider and logs in. You create a widget session from your backend with one API call, then send the user to the URL it returns.

Already live with /auth/generateWidgetSession? It keeps working today, with deprecation planned for 3 November 2026. It is documented under Legacy endpoint at the bottom of this page, with migration notes for moving to the redesigned widget.

Create a widget session

From your backend, call POST https://access.tryterra.co/api/widget/session with your dev-id and x-api-key headers.

Command Line
curl --request POST --url https://access.tryterra.co/api/widget/session \
  --header 'dev-id: <YOUR-DEV-ID>' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
      "reference_id": "my_first_connection",
      "auth_success_redirect_url": "https://example.com/success",
      "auth_failure_redirect_url": "https://example.com/failure"
  }'
import requests

response = requests.post(
    "https://access.tryterra.co/api/widget/session",
    headers={"dev-id": "<YOUR-DEV-ID>", "x-api-key": "<YOUR-API-KEY>"},
    json={
        "reference_id": "my_first_connection",
        "auth_success_redirect_url": "https://example.com/success",
        "auth_failure_redirect_url": "https://example.com/failure",
    },
)

widget_url = response.json()["url"]

Use reference_id to pass your own end user's ID. It comes back on the authentication event and on the success redirect, so you can match the Terra User to your end user without any extra lookups.

Request body

All fields are optional. With no providers field, the widget shows the data sources you have enabled in your Terra Dashboard.

Field
Type
Description

reference_id

string

Your identifier for the end user (a user ID or email on your system).

providers

string

Comma-separated list of providers to show, in the order given, e.g. "GARMIN,OURA,FITBIT". A single provider skips the selection screen and goes straight to that login.

auth_success_redirect_url

string

Where to send the user after a successful connection.

auth_failure_redirect_url

string

Where to send the user after a failed or abandoned connection.

show_disconnect

boolean

Show a disconnect button next to providers already connected under this reference_id. Defaults to true when a reference_id is given; set false to hide it.

multi_auth

boolean

Keep the user on the widget after each successful connection so they can connect several providers in one session. Default false.

connected_uids

string[]

Terra user_ids already connected for this end user; their providers show as connected with a disconnect option. Unknown IDs return a 400.

bypass_feedback

boolean

Set false to keep the user on the widget's own result screen instead of redirecting them to your URL immediately.

sdk_app

string

Set to "grip" to send Apple Health, Health Connect and Samsung Health connections to Terra Grip, for users without your own app. Any other value returns a 400.

use_terra_avengers_app

boolean

Allow Apple Health connections through the Terra mobile app. Default false.

apple_app_url

string

URL of your own iOS app to hand Apple Health connections to, instead of the Terra mobile app.

samsung_app_url

string

URL of your own Android app to hand Samsung Health connections to.

The widget is shown in the end user's own language, negotiated from their browser's Accept-Language header (English fallback). There is nothing to set on the request.

Read the widget URL

A successful call returns 201 with the widget URL in the "url" field.

The URL is valid for expires_in seconds (24 hours). Create a fresh session each time a user starts the connect flow rather than storing URLs.

Status
Meaning

201

Session created; url is ready to open.

400

A field is malformed. message explains which; invalid_user_ids lists any connected_uids that do not exist.

other

status is "error" and message explains why. Most often the dev-id / x-api-key pair is not valid for this environment.

Open the widget URL

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

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

  • or a new tab, if using a web app.

Your end user picks a provider, logs in, grants permissions, and is sent to your auth_success_redirect_url with their Terra user_id and your reference_id as query parameters. At the same time, an authentication event is sent to your destination: see Handle the auth event.

Make it yours. The widget's name, logo and colours are set in your Terra Dashboard under Authentication, where you can also preview the widget and test a connection before shipping. The permissions list can be customised through your Terra Dashboard too.

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

Avoid common mistakes

Migrate from /auth/generateWidgetSession

Existing integrations keep working today, and the legacy endpoint is planned for deprecation on 3 November 2026. Accounts created after 3 September 2026 cannot use it at all. If you want the redesigned widget, the changes are small:

Legacy (/v2/auth/generateWidgetSession)

Redesigned widget (/api/widget/session)

POST https://api.tryterra.co/v2/auth/generateWidgetSession

POST https://access.tryterra.co/api/widget/session, with the same dev-id / x-api-key headers.

"language": "en" in the body

Remove it. The widget follows the end user's browser language automatically.

"providers": "multi-auth"

Send "multi_auth": true instead, alongside your providers list.

"providers": "ALL"

Omit providers. The widget then shows exactly the data sources you have enabled in your Dashboard.

Response expires_in: 900

Response expires_in: 86400. Otherwise the response shape (session_id, url, status, expires_in) is unchanged.

Widget styled from the legacy dashboard settings

Styled from Dashboard > Authentication. Your name and logo carry over; bespoke legacy themes do not.

Everything else works the same way: reference_id, redirect URLs, show_disconnect, connected_uids, use_terra_avengers_app, and the authentication events you receive.

Legacy endpoint

Call /auth/generateWidgetSession from your backend:

The response has the same shape as the redesigned widget, with the URL on widget.tryterra.co and expires_in of 900 seconds:

Open the url the same way: a new tab, or an in-app browser on mobile.

Next steps

Last updated

Was this helpful?