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
  • 1. Build your UI
  • 2. Make an API Request
  • 3. Parse the Auth URL from the JSON Response
  • 4. Open The Auth URL
  • ❌ Common Mistakes

Was this helpful?

  1. Health & Fitness API
  2. User authentication

Implementation (Custom UI)

PreviousImplementation (Terra widget)NextHandling authentication events

Last updated 20 days ago

Was this helpful?

1. Build your UI

First, create a button for each data source that a user might want to connect. (e.g. a "Connect to Fitbit" button). You may take inspiration from the Terra Widget when creating your own UI.

You may use the endpoint to fetch metadata for each source available through Terra when creating your UI. This enables you to dynamically retrieve the sources you’ve (using the enabled boolean parameter in the response), along with their associated metadata, such as available data types, display names, and logos.


2. Make an API Request

From your backend, call the to generate an authentication link

Use the parameter resource to pass a source name (e.g. "oura" , "withings" ..)

Command Line
curl --request POST --url https://api.tryterra.co/v2/auth/authenticateUser?resource=oura \
  --header 'dev-id: <YOUR-DEV-ID>' \
  --header 'x-api-key: <YOUR-API-KEY> \
  --header 'Content-Type: application/json' \
  --data '{
      "language": "en",
      "reference_id": "my_first_connection",
      "auth_success_redirect_url": "text",
      "auth_failure_redirect_url": "text"
  }'

Pro tip: Use reference_id in your request Body to pass in your own end user's ID on your system.


3. Parse the Auth URL from the JSON Response

The endpoint will generate an authentication url in the response. Retrieve it by parsing "auth_url" .

JSON
{
  "status": "success",
  "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "auth_url": "https://cloud.ouraring.com/oauth/authorize?response_type=code&client_id=...&redirect_uri=https%3A%2F%2Fapi.tryterra.co%2Fv2%2Fauth%2Foura%2Foauth2&scope=email+spo2+session+heartrate+personal+daily+workout+tag.."
}

4. Open The Auth URL

Pass the retrieved "auth_url" to your client side, and open it either in:

  • an in-app browser, if using a mobile app,

  • or a new tab, if using a web app


❌ Common Mistakes

Common Mistakes and Best Practices

  • Do not call the API from your frontend, as this will lead to a CORS error.

  • Do not use WebView or iFrame for the authentication flow. Using them poses security risks due to the invisible URL bar, meaning that the user cannot know the domain onto which they are entering their username & password. Providers may completely block authentication leading to an error during the flow. Instead, use a new tab or an in-app browser to open the URL returned by the /auth endpoints.

See details in the

This will simplify reconciling the terra with your end user.

This will take the user straight to the login screen so they can connect it.

The permissions list can be

Do not expose your API credentials. Instead, always call the endpoints from your backend.

API Reference Page.
customised through your Terra Dashboard
activated in your Dashboard
Login Screen (example: Oura)
Permission screen (example: Oura)
/integrations/detailed
/auth/authenticateUser
User
data source's
/auth