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.
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.
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"]Request body
All fields are optional. With no providers field, the widget shows the data sources you have enabled in your Terra Dashboard.
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.
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.
You can find a list of all your authenticated users in:
Or by using
GET /subscriptions
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
Authentication redirect pages: send the end user back to your app after they connect.
Handle the auth event: store the
user_idTerra sends when the connection succeeds.Health data events: process the data Terra sends for connected users.
Last updated
Was this helpful?