Connect a User
Allow users to link their wearable devices with their health & fitness devices and apps so they can receive data
Last updated
Was this helpful?
Allow users to link their wearable devices with their health & fitness devices and apps so they can receive data
Last updated
Was this helpful?
API Key:
Obtain your API Key from the Terra Dashboard
Set up a webhook where Terra will send event updates.
Enable the specific data sources your app requires (e.g., activity, sleep, body metrics).
Connecting a is equivalent to creating a connection to one 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
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 endpoint
This allows you to test out the flow that an end user will follow when connecting their own wearable device
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
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
The response will take the following form:
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
The end user will then need to log in and agree to the permissions requested by Terra
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)
If the user declines required permissions, or cancels authentication halfway through, you will receive an appropriate Event
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
This is done not to create duplicate records for a single account for a given dev ID.
To connect to :
Apple Health
Samsung Health
Google Fit
you will need to use the
For demonstration purposes, if this is your first time connecting a , 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.
Instead, opt to use an in-app browser to open the URL returned by the or the endpoint
Use 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 with your
This will take the to a device selection screen
Once the selects a source to connect to, they will be taken to that login screen
The permissions list below can be
After finishing authentication, the end user will be redirected either to a default success/failure page, or to the one you passed into the as auth_success_redirect_url or auth_failure_redirect_url, respectively.
The user_id, reference_id, and source connected will be appended to the final URL, i.e.
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.
Use the 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 with your
With the auth_url retrieved above. This will take the user straight to a login screen
The permissions list below can be
After finishing authentication, the end user will be redirected either to a default success/failure page, or to the one you passed into the as auth_success_redirect_url or auth_failure_redirect_url, respectively.
The user_id, reference_id, and source connected will be appended to the final URL, i.e.
Upon finishing the last step in the guide above, in either of the two implementations, you will in your .
Upon , you will notice that you received an auth event upon connection
This signifies a new has been created, following them logging into the login/authentication link provided to them.
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 in your system.
This means that you should maintain a possibility for a one-to-many mapping between Terra and , as the same wearable account could be connected to multiple end users, with different reference_ids
