> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/unified-api/implementation-terra-widget.md).

# 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.

{% hint style="info" %}
**Already live with `/auth/generateWidgetSession`?** It keeps working today, with deprecation planned for 3 November 2026. It is documented under [Legacy endpoint](#legacy-endpoint) at the bottom of this page, with [migration notes](#migrate-from-auth-generatewidgetsession) for moving to the redesigned widget.
{% endhint %}

## 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.

{% tabs %}
{% tab title="cURL" %}
{% code title="Command Line" %}

```bash
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"
  }'
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}

```python
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"]
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
import axios from "axios";

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

const widgetUrl = data.url;
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Use `reference_id` to pass your own end user's ID. It comes back on the [authentication event](https://docs.tryterra.co/unified-api/authentication-flow.md#handle-the-auth-event) and on the success redirect, so you can match the Terra [User](https://docs.tryterra.co/introduction/core-concepts#users) to your end user without any extra lookups.
{% endhint %}

### Request body

All fields are optional. With no `providers` field, the widget shows the data sources you have enabled in your [Terra Dashboard](https://dashboard.tryterra.co/).

| 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_id`s 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](https://docs.tryterra.co/mobile-sdks/terra-grip-companion-app.md), 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.

{% code title="JSON" lineNumbers="true" %}

```json
{
  "session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "url": "https://access.tryterra.co/widget/session/23dc2540-7139-44c6-8158-f81196e2cf2e",
  "status": "success",
  "expires_in": 86400
}
```

{% endcode %}

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](https://docs.tryterra.co/introduction/core-concepts#end-users-and-reference-ids) 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](https://docs.tryterra.co/unified-api/authentication-flow.md#handle-the-auth-event).

{% hint style="info" %}
**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](https://docs.tryterra.co/unified-api/setting-up-data-sources.md#choose-data-types) too.
{% endhint %}

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

* Your [Terra Dashboard > Users](https://dashboard.tryterra.co/dashboard/users)
* Or by using [`GET /subscriptions`](https://docs.tryterra.co/reference/health-and-fitness-api/user#get-subscriptions)

## Avoid common mistakes

{% hint style="danger" %}

* Do not expose your API credentials. Always create the widget session 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.
* Do not reuse widget URLs across users or sessions. Each `url` belongs to one `reference_id`; create a new session per connect attempt.
  {% endhint %}

## 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

{% hint style="warning" %}
`POST /auth/generateWidgetSession` is deprecated, with deprecation planned for **3 November 2026**. Existing apps keep working, and we will give notice well before any breaking change. Accounts created after 3 September 2026 get a `410` error pointing to `POST https://access.tryterra.co/api/widget/session`.
{% endhint %}

Call [`/auth/generateWidgetSession`](https://docs.tryterra.co/reference/health-and-fitness-api/authentication#post-auth-generatewidgetsession) from your backend:

```bash
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": "https://example.com/success",
      "auth_failure_redirect_url": "https://example.com/failure"
  }'
```

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

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

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

## Next steps

* [Authentication redirect pages](https://docs.tryterra.co/unified-api/customising-authentication-redirects.md): send the end user back to your app after they connect.
* [Handle the auth event](https://docs.tryterra.co/unified-api/authentication-flow.md#handle-the-auth-event): store the `user_id` Terra sends when the connection succeeds.
* [Health data events](https://docs.tryterra.co/unified-api/receiving-data-updates.md): process the data Terra sends for connected users.
