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. Make an API Request
  • 2. Parse the Widget URL from the JSON Response
  • 3. Open The Widget URL
  • ❌ Common Mistakes

Was this helpful?

  1. Health & Fitness API
  2. User authentication

Implementation (Terra widget)

PreviousAuthentication flowNextImplementation (Custom UI)

Last updated 20 days ago

Was this helpful?

1. Make an API Request

Make an API Request to the endpoint from your backend.

Command Line
curl --request POST --url https://api.tryterra.co/v2/auth/generateWidgetSession \
  --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.

This will simplify reconciling the Terra with your end user.


2. Parse the Widget URL from the JSON Response

The endpoint will generate a widget url in the response. Retrieve it by parsing "url" .

JSON
{
   "session_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
   "url": "https://widget.tryterra.co/session/344d475f-296a-489a-a88c-54183671dafd",
   "status": "success",
   "expires_in": 900
}

3. Open The Widget URL

Pass the retrieved "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

You can find a list of all your authenticated users in:


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

This will take your to the provider selection screen, the Terra authentication widget.

The permissions list can be

Your

Or by using

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

customised through your Terra Dashboard
Terra Dashboard > Users
Device Selection screen (Terra authentication widget)
Login Screen (example: Oura)
Permission screen (example: Oura)
/auth/generateWidgetSession
User
end user
the /subscriptions endpoints
/auth