User authentication

Securely connect your users' health data sources to your application via Terra.

User authentication allows Terra to accessing your users' health and fitness data and is essential to using the Health & Fitness API.

Authentication allows your end-users to grant your application permission to retrieve data from their wearables or fitness platforms (like Fitbit, Garmin, Oura, etc.). Once a user is successfully authenticated, Terra automatically pushes their health data events to your configured destination.

---

Implementation guides

1

Authentication flow overview

Get an overview of the user authentication process, from the initial user action in your app to receiving their Terra User ID.

2

Authenticating with the Terra widget

The quickest way to get started. Learn how to integrate Terra's pre-built, customisable UI to handle the provider selection and authentication process with a single API call.

3

Handling authentication events

Understand the different types of authentication events Terra sends (success, failure, deauthorisation) and how to process their payloads effectively.

---

Configuration

Customising authentication redirects

• Learn how to customise the success or failure screen that users see after they complete the authentication flow but before they are redirected back to your app.

Authenticating with your own UI

• For maximum control over the user experience. This guide details how to build your own device connection screen and use Terra's API to authenticate users with specific providers.

💡 Pro-Tip: Start with the widget because it’s the:

1. Fastest way to go live: no need to build or maintain your own auth UI

2. Easiest to implement: just one backend call to generate the link

3. Optimized UX: designed and tested for high end-user completion rates across devices and platforms

---

✅ Checklist

Implementing the User Authentication in your App

1. API:

   1. Credentials: Did you find your Terra API Keys and Dev-ID in your Terra Dashboard?

   2. Endpoint: Did you make a successful request from your backend to one of the /auth endpoints?

      1. POST /auth/generateWidgetSession

      2. POST /auth/authenticateUser?resource=oura

   3. Response: Did you get a 200 response and parse the authentication url? Either:

      1. "url": the widget screen (via the widget endpoint)

      2. "auth_url" : the provider's login screen (via the authenticateUser endpoint)

   4. End-user: Was your end-user redirected to an Auth Success Screen?

2. Event: Did you receive an Success "Authentication Event" to your destination?

3. Database: Did you save this user in your Database using user_id ?