Terra Docs
Dashboard
  • Docs
  • API Reference
  • Changelog
  • Getting Started
    • What is Terra API?
    • Account setup and API keys
    • Core concepts
  • Health & Fitness API
    • Overview
    • Quickstart
    • Integration setup
      • Understanding sources and destinations
      • Setting up data sources
      • Setting up data destinations
        • Webhooks
        • SQL database (Postgres, MySQL)
        • Supabase
        • Cloud storage (S3, GCP)
        • Queuing services (SQS, Kafka)
      • Customising data types
      • Dedicated data source API keys
      • Understanding Terra environments
    • User authentication
      • Authentication flow
      • Implementation (Terra widget)
      • Implementation (Custom UI)
      • Handling authentication events
      • Customising authentication redirects
    • Managing user health data
      • Receiving health data updates (events)
      • Requesting historical health data (REST API requests)
      • Writing data
    • Mobile-only sources
      • iOS (Swift)
      • Android (Kotlin)
      • React Native
      • Flutter
    • Troubleshooting
    • Pricing
  • User Engagement
    • Health Scores
  • Streaming API
    • Overview
    • Wearable -> Your app
      • iOS (Swift)
      • Android
    • Your app -> Terra
      • iOS (Swift)
      • Android
    • Terra -> Your backend
  • Teams API
  • Biomarkers API - Upcoming
Powered by GitBook
On this page
  • Overview
  • The Authentication Flow
  • Test the Authentication

Was this helpful?

  1. Health & Fitness API
  2. User authentication

Authentication flow

PreviousUser authenticationNextImplementation (Terra widget)

Last updated 20 days ago

Was this helpful?

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 , you need to have completed the following steps:

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

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

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

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!

For internal demonstration purposes, if this is your first time authenticating a , you may connect your own data source using the as below.

API Key & dev-id:
Terra Dashboard
Destination Configured:
Data Sources Activated:
User
User