Manual connection via the API

Getting Started

Setting up

Authenticate Users

Getting Data

Parsing Data

API Settings

Mobile Setup






Data Models

1. Creating a session

To connect one specific wearable, you can generate a connection URL to its platform using the Authenticate User endpoint, or using a provided client:

auth_resp = terra.generate_authentication_url(
  reference_id="USER ID IN YOUR APP",


resource is the provider your user wants to connect.

The following are optional parameters:

reference_id is how you store the user in your app (useful when one user connects multiple wearables to Terra)
auth_success_redirect_url is where the user is redirected upon a successful authentication
auth_failure_redirect_url is where the user is redirected upon a failure in the authentication

Note: ensure that the redirect URLs are accessible by HTTPS (they must have https:// appended in front).

You should receive an API response with a URL to the login session.

  "status": "success",
  "user_id": "ae538288-42a8-4fd5-8bf4-33902c3bc458",
  "auth_url": ""

2. Displaying the session

For a webapp, you can simply open a new tab with the login page URL and redirect the user to that screen.

For mobile we severely discourage using a webview to display the screen. You will face issues with certain providers, as webviews hide the URL from the users. To avoid this, use an in-app browser, which displays the URL at all times to the user.

Generate the URL to a connection page using the auth/authenticateUser endpoint

Generate the URL to a connection page using the auth/authenticateUser endpoint

3. Confirming a user authentication

Once authentication has been completed, your users will be redirected to the auth_success_redirect_url you passed in, or to a default Terra Connect success URL. You are encouraged to provide a deep link in order to redirect users back into your app. Setting auth_success_redirect_url as a deep link or a web endpoint on your backend will allow you to be notified when a user successfully authenticates.

The connection's user_id, resource, and reference_id will be appended as query parameters as such:


user_id identifies the wearable that was just authenticated. One user on your app (which can be identified byreference_id) may be associated with multiple user_id s if they connect multiple wearables.

You will also receive a webhook message when a user successfully authenticates. Webhooks will be explained in-depth in the next section.