Connect a User

Allow users to link their wearable devices with their health & fitness devices and apps so they can receive data

Prerequisites

1. API Key:

   • Obtain your API Key from the Terra Dashboard

2. Destination Configured:

   • Set up a webhook where Terra will send event updates.

3. Data Sources Enabled:

   • Enable the specific data sources your app requires (e.g., activity, sleep, body metrics).

4. Receiving authentication events reviewed

Overview

Connecting a User is equivalent to creating a connection to one Provider account.

You can connect a user through Terra through 3 principal methods.

• Through the Dashboard UI, for testing and demo purposes

• Through Terra's pre-build authentication widget

• Through building your own UI

User limits

Note that for testing & development, there is a user limit of 50 users on each environment.

If you reach the user limit, kindly deregister testing accounts you no longer need using the #auth-deauthenticateuser endpoint

SDK providers

To connect to SDK-based integrations:

Apple Health

Samsung Health

Google Fit

you will need to use the appropriate SDK functions instead, outlined in the mobile SDK-specific guide

Connect your first user

For demonstration purposes, if this is your first time connecting a User, you may connect one using the Terra Dashboard UI as below. This will help you understand the connection flow for a User without making any API calls yourself.

This allows you to test out the flow that an end user will follow when connecting their own wearable device

Build your own authentication flow

NEVER use a Webview or iframe to authenticate a user

Using a webview pauses 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, opt to use an in-app browser to open the URL returned by the #auth-generatewidgetsession or the #auth-authenticateuser endpoint

Choose your implementation

Terra offers you the option of using the pre-built authentication Widget in order to authenticate, or the ability to create your custom UI for users to select which health & fitness data source to connect.

• The Terra Widget provides a customizable UI with just a single API call, offering options to adjust colors, edit text, and specify the devices available for user connection.

• Building your own UI gives you complete control over every pixel of the device connection screen, at the cost of additional development time

Using the Terra Widget

Example digram for widget flow

Use the widget session endpoint in your backend to generate an authentication link, and retrieve the url from the response.

Pro tip: Use the reference_id parameter to pass in your own end user's ID on your system, to reconcile a terra user with your end user

The response will take the following form:

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

Pass the URL retrieved to your client side, and open either

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

• a new tab, if using a web app

This will take the end user to a device selection screen

Device selection screen

Once the end user selects a source to connect to, they will be taken to that source's login screen

Example login screen for Oura

The end user will then need to log in and agree to the permissions requested by Terra

The permissions list below can be customized through your Terra Dashboard

Permission screen for Oura

After finishing authentication, the end user will be redirected either to a default success/failure page, or to the one you passed into the widget session endpoint as auth_success_redirect_url or auth_failure_redirect_url, respectively.

This may be

• a page on your web app with any query parameters of your choice (e.g. https://somreallycoolcompany.com?terra_auth_success=true)

• A deep link into your mobile app (e.g. reallycoolapp://success)

The user_id, reference_id, and source connected will be appended to the final URL, i.e. https://widget.tryterra.co/session/demo/success?user_id=bc205b50-dabe-4680-9d35-38517b915dc1&resource=GOOGLE&reference_id=null

Using your own 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 /integrations/detailed endpoint to fetch metadata for each source available through Terra when creating your UI.

This enables you to dynamically retrieve the sources you’ve activated in your Dashboard (using the enabled boolean parameter in the response), along with their associated metadata, such as available data types, display names, and logos.

Use the User connection endpoint in your backend to generate an authentication link, and retrieve the auth_url from the response.

Pro tip: Use the reference_id parameter to pass in your own end user's ID on your system, to reconcile a terra User with your end user

The response will take the following form:

{
  "status": "success",
  "user_id": "23dc2540-7139-44c6-8158-f81196e2cf2e",
  "auth_url": "https://www.fitbit.com/oauth2/authorize?response_type=code&client_id=23BBG9&scope=settings+nutrition+sleep+heartrate+electrocardiogram+weight+respiratory_rate+oxygen_saturation+profile+temperature+cardio_fitness+activity+location&state=bLqqjPie9ptwoWm6VBxHCu6JkkoWJp"
}

Pass the URL retrieved to your client side, and open either

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

• a new tab, if using a web app

With the auth_url retrieved above. This will take the user straight to a data source's login screen

Example login screen for Oura

The end user will then need to log in and agree to the permissions requested by Terra

The permissions list below can be customized through your Terra Dashboard

Permission screen for Oura

After finishing authentication, the end user will be redirected either to a default success/failure page, or to the one you passed into the User connection endpoint as auth_success_redirect_url or auth_failure_redirect_url, respectively.

This may be

• a page on your web app with any query parameters of your choice (e.g. https://somreallycoolcompany.com?terra_auth_success=true)

• A deep link into your mobile app (e.g. reallycoolapp://success)

The user_id, reference_id, and source connected will be appended to the final URL, i.e. https://widget.tryterra.co/session/demo/success?user_id=bc205b50-dabe-4680-9d35-38517b915dc1&resource=GOOGLE&reference_id=null

Upon finishing the last step in the guide above, in either of the two implementations, you will receive an authentication success event in your destination.

User authentication events

Upon Connecting a User, you will notice that you received an auth event upon connection

{
  "type": "auth",
  "status": "success",
  "widget_session_id": "a9a0c7a4-c05e-4550-a973-f87a31a7c558",
  "user": {
    "scopes": "COURSE_IMPORT,WORKOUT_IMPORT,ACTIVITY_EXPORT,HEALTH_EXPORT",
    "active": true,
    "last_webhook_update": null,
    "created_at": "2024-10-07T03:45:00.000000+00:00",
    "user_id": "4735eac4-31a2-47ef-8b11-51e98d84c680",
    "reference_id": "tony_stark",
    "provider": "GARMIN"
  },
  "reference_id": "tony_stark",
  "message": "User has successfully authenticated",
  "version": "2022-03-16"
}

This Event signifies a new User has been created, following them logging into the login/authentication link provided to them.

The user_id provided in this response is crucial to the functioning of Terra. It will be sent in all #data-events and needs to be used whenever you Request Historical data

If the user declines required permissions, or cancels authentication halfway through, you will receive an appropriate Event

{
  "type": "auth",
  "status": "error",
  "message": "User failed to authenticate and has been deleted",
  "reference_id": "test-username",
  "widget_session_id": "3a35549e-501a-49ad-8c10-6703b526bb9e",
  "user": {
    "last_webhook_update": null,
    "user_id": "6bd4a5a9-a613-4060-b737-6767b5b1dfa7",
    "scopes": null,
    "active": true,
    "provider": "GARMIN",
    "reference_id": "test-username",
    "created_at": null
  },
  "reason": "auth_cancelled",
  "version": "2022-03-16"
}

This notifies your system that a new fitness data account has been created. Store this connection in your database, using the "reference_id" field to reconcile them back to an End User in your system.

User reauthentication

Connecting the same account twice on the same dev_id will ALSO lead to the following event being sent.

Connecting an account a second time on the same dev_id will delete the previous user record for that account, and yield a new user_id. You will receive both an auth success event as well as a reauthentication event, as detailed below

{
  "type": "user_reauth",
  "new_user": {
    "last_webhook_update": null,
    "user_id": "6bd4a5a9-a613-4060-b737-6767b5b1dfa7",
    "scopes": "COURSE_IMPORT,WORKOUT_IMPORT,ACTIVITY_EXPORT,HEALTH_EXPORT",
    "active": true,
    "provider": "GARMIN",
    "reference_id": "tony_stark",
    "created_at": "2024-10-07T03:45:00.000000+00:00"
  },
  "old_user": {
    "scopes": "COURSE_IMPORT,WORKOUT_IMPORT,ACTIVITY_EXPORT,HEALTH_EXPORT",
    "active": true,
    "last_webhook_update": null,
    "created_at": "2024-10-07T03:45:00.000000+00:00",
    "user_id": "4735eac4-31a2-47ef-8b11-51e98d84c680",
    "reference_id": "tony_stark",
    "provider": "GARMIN"
  },
  "status": "warning",
  "message": "User has reauthenticated and old ID has been deleted"
}

This is done not to create duplicate records for a single account for a given dev ID.

This means that you should maintain a possibility for a one-to-many mapping between Terra Users and End Users, as the same wearable account could be connected to multiple end users, with different reference_ids