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
  • Implementation guides
  • Configuration
  • βœ… Checklist

Was this helpful?

  1. Health & Fitness API

User authentication

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

PreviousUnderstanding Terra environmentsNextAuthentication flow

Last updated 17 days ago

Was this helpful?

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

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

2

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

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


Configuration

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

  • 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 ?

Authentication flow overview
Authenticating with the Terra widget
Handling authentication events
Customising authentication redirects
Authenticating with your own UI