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.

Prerequisites

To connect a User, you need to have completed the following steps:

1. API Key & dev-id: Obtain your API Key and dev-id from your Terra Dashboard

2. Destination Configured: Set up a Data Destination where Terra will send events and data updates.

3. Data Sources Activated: Enable the data sources (e.g. oura).

---

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, you may connect your own data source using the Terra Dashboard 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!