# Authentication flow

## Overview

Authenticating a user via Terra is the **first** and **most** **essential** **step** to begin receiving their health and fitness data from their wearable or fitness platform.

A **user authentication** is the process of allowing your end-user to connect their health data (e.g., Fitbit, Garmin, Oura) to you via Terra API. Once authenticated, Terra will start automatically pushing health data **events** from that user's account to your chosen data destination, with no polling or manual requests required.<br>

{% hint style="success" %}

### **Prerequisites**

To connect a [User](/reference/health-and-fitness-api/core-concepts.md#user), you need to have completed the following steps:

1. [**API Key & dev-id:**](https://dashboard.tryterra.co/) Obtain your **API** **Key** and **dev-id** from your Terra Dashboard
2. [**Destination Configured:**](/health-and-fitness-api/integration-setup.md#set-up-your-data-sources-and-destinations) Set up a Data Destination where Terra will send **events** and **data** **updates**.
3. [**Data Sources Activated**:](/health-and-fitness-api/integration-setup.md#set-up-your-data-sources-and-destinations) Enable the data **sources** (e.g. oura).
   {% endhint %}

***

## The Authentication Flow

The ideal authentication flow for your end-users:

* User clicks "Connect Device" in your mobile app or web app.
* Your frontend requests your backend for a widget URL.
* Your backend generates a widget URL by calling the `/auth/generateWidgetSession` endpoint.
* Redirect the user to the widget URL in your frontend (or open in-app browser for mobile apps).
* User authenticates their data source.
* Widget redirects to your success/failure URL with the `user_id` and `reference_id`.

The health and fitness data of your end-users will be sent to your destination automatically thereafter!

You **don't** **need** to manage **auth** **tokens** or **refresh** **tokens**; we manage this on our end on your behalf.

***

## Test the Authentication

For internal demonstration purposes, if this is your first time authenticating a [User](/reference/health-and-fitness-api/core-concepts.md#user), you may connect your own data source using the [Terra Dashboard](https://dashboard.tryterra.co/) as below.

Your end-users won't use this pathway to connect their wearables; to connect live users you need to use the API. However, this will help you understand the auth flow without making any API calls yourself!

{% @supademo/embed url="<https://app.supademo.com/demo/clzvfyvwy08lmo0qpw5yadcf8>" demoId="clzvfyvwy08lmo0qpw5yadcf8" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryterra.co/health-and-fitness-api/user-authentication/authentication-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.