adaptationio/terra-connections

Terra Connections

Connect users to 150+ wearable devices and health data providers.

Supported Providers (150+)

Wearables & Fitness Trackers

• Garmin - All models, full historical data
• Fitbit - All devices, nutrition support
• Apple Health - iOS SDK required
• Oura Ring - Sleep, readiness, activity
• WHOOP - Recovery, strain, sleep
• Polar - Training, sleep, activity
• Withings - Watches, scales, blood pressure
• Samsung Health - Android SDK required
• Google Fit / Health Connect - Android SDK required
• Suunto, Coros, Biostrap, Zepp - Full support

Nutrition Apps

• MyFitnessPal - Food logging, macros
• Cronometer - Detailed nutrition
• MacrosFirst, FatSecret - Meal tracking

Medical Devices

• Freestyle Libre - CGM glucose data
• Dexcom - CGM glucose (special process)
• Omron - Blood pressure monitors

Connection Methods

Method 1: Widget Flow (Recommended)

Pre-built UI, easiest integration:

from terra import Terra

client = Terra(
    dev_id=os.environ["TERRA_DEV_ID"],
    api_key=os.environ["TERRA_API_KEY"]
)

# Generate widget session
response = client.authentication.generatewidgetsession(
    reference_id="user_12345",  # Your internal user ID
    auth_success_redirect_url="https://app.botaniqal.com/success",
    auth_failure_redirect_url="https://app.botaniqal.com/failure",
    providers=["FITBIT", "GARMIN", "OURA"]  # Optional: filter providers
)

widget_url = response.url
# Redirect user to widget_url

User Flow:

1. User visits widget URL
2. Selects provider (Fitbit, Garmin, etc.)
3. Completes OAuth with provider
4. Redirected to success URL
5. Webhook sent to your endpoint with type: "auth"

Method 2: Custom UI Flow

Build your own provider selection UI:

# Step 1: Get available integrations
integrations = client.integrations.fetch()
# Display provider list in your UI

# Step 2: User selects provider, generate auth URL
response = client.authentication.authenticateuser(
    resource="FITBIT",  # Provider selected by user
    reference_id="user_12345"
)

auth_url = response.auth_url
# Open auth_url in browser (NOT WebView/iFrame!)

Important: Always open auth URLs in a real browser, not WebView or iFrame (OAuth security requirement).

Method 3: Mobile SDK (Required for Apple/Samsung/Health Connect)

These sources have no web API - mobile SDK required:

iOS (Swift) - Apple Health:

import TerraiOS

// 1. Get token from your backend
let token = await fetchTerraToken()

// 2. Initialize Terra
Terra.initTerra(devId: "botaniqalmedtech-testing-SjyfjtG33s", referenceId: "user_12345")

// 3. Connect to Apple Health
Terra.initConnection(
    type: Connections.APPLE_HEALTH,
    token: token,
    schedulerOn: true  // Enable background sync
) { success, error in
    if success {
        print("Connected to Apple Health!")
    }
}

Android (Kotlin) - Samsung Health / Health Connect:

import co.tryterra.terra.Terra

// 1. Get token from your backend
val token = fetchTerraToken()

// 2. Initialize Terra (minSDK 28 required)
Terra.initTerra(
    devId = "botaniqalmedtech-testing-SjyfjtG33s",
    referenceId = "user_12345",
    context = this
)

// 3. Connect to Samsung Health or Health Connect
Terra.initConnection(
    connection = Connections.SAMSUNG,  // or Connections.HEALTH_CONNECT
    token = token,
    context = this,
    schedulerOn = true
) { success ->
    if (success) {
        println("Connected to Samsung Health!")
    }
}

React Native:

import { Terra, Connections } from "terra-react";

// Initialize
Terra.initTerra("botaniqalmedtech-testing-SjyfjtG33s", "user_12345");

// Connect (iOS: Apple Health, Android: Samsung/Health Connect)
await Terra.initConnection(
    Connections.APPLE_HEALTH,
    authToken,
    true  // schedulerOn for background sync
);

Operations

connect-user

Connect a user to a wearable provider.

def connect_user(
    client: Terra,
    reference_id: str,
    provider: str = None,
    success_url: str = None,
    failure_url: str = None
) -> dict:
    """
    Connect user to wearable provider.

    Args:
        reference_id: Your internal user ID
        provider: Specific provider or None for widget with all
        success_url: Redirect URL on success
        failure_url: Redirect URL on failure

    Returns:
        dict with url and session_id
    """
    if provider:
        # Custom UI flow - specific provider
        response = client.authentication.authenticateuser(
            resource=provider,
            reference_id=reference_id
        )
        return {"url": response.auth_url, "type": "direct"}
    else:
        # Widget flow - user selects provider
        response = client.authentication.generatewidgetsession(
            reference_id=reference_id,
            auth_success_redirect_url=success_url,
            auth_failure_redirect_url=failure_url
        )
        return {
            "url": response.url,
            "session_id": response.session_id,
            "type": "widget"
        }

disconnect-user

Disconnect user and remove their data.

def disconnect_user(client: Terra, terra_user_id: str) -> bool:
    """
    Disconnect user from Terra (revokes access, removes data).

    Args:
        terra_user_id: Terra's user ID (not your reference_id)

    Returns:
        bool: Success status
    """
    response = client.authentication.deauthenticateuser(user_id=terra_user_id)
    return response.success

get-user-info

Get user's connection status and details.

def get_user_info(client: Terra, terra_user_id: str) -> dict:
    """Get information about a connected user."""

    response = client.user.getuser(user_id=terra_user_id)

    return {
        "user_id": response.user.user_id,
        "provider": response.user.provider,
        "reference_id": response.user.reference_id,
        "scopes": response.user.scopes,
        "last_webhook_update": response.user.last_webhook_update
    }

list-connected-users

Get all users connected to your app.

def list_connected_users(client: Terra) -> list:
    """List all connected Terra users."""

    response = client.user.getsubscriptions()

    users = []
    for user in response.users:
        users.append({
            "user_id": user.user_id,
            "provider": user.provider,
            "reference_id": user.reference_id,
            "last_update": user.last_webhook_update
        })

    return users

get-users-by-reference

Find Terra users by your internal reference ID.

def get_users_by_reference(client: Terra, reference_id: str) -> list:
    """
    Get all Terra users for a reference_id.
    (One person can have multiple providers connected)
    """

    response = client.user.getuser(reference_id=reference_id)

    return response.users  # List of TerraUser objects

Multi-Device Setup

One user can connect multiple wearables:

# User connects Fitbit
connect_user(client, "user_123", provider="FITBIT")

# Same user connects Oura Ring
connect_user(client, "user_123", provider="OURA")

# Get all connections for user
users = get_users_by_reference(client, "user_123")
# Returns: [TerraUser(provider="FITBIT"), TerraUser(provider="OURA")]

Each provider creates a separate Terra User ID, but all share the same reference_id.

Provider-Specific Notes

Apple Health (iOS)

• Requires: Mobile SDK, iOS 13+
• No web API: Must use native app
• Background sync: Enable schedulerOn: true
• Permissions: Request during connection

Samsung Health / Health Connect (Android)

• Requires: Mobile SDK, minSDK 28
• Health Connect: Google's unified health API
• Samsung specific: Uses Samsung Health SDK

WHOOP

• Special process: Contact Terra for activation
• Data: Recovery, strain, sleep, HRV

Dexcom (CGM)

• Special process: Contact Terra for activation
• Data: Continuous glucose monitoring

Freestyle Libre (EU)

• Dedicated API keys: Required for EU
• Data: CGM glucose readings

Strava

• Dedicated API keys: Required
• Data: Activities, routes

Webhook Events for Connections

When user connects/disconnects, you receive webhooks:

Connection Success (type: "auth"):

{
  "type": "auth",
  "user": {
    "user_id": "terra_abc123",
    "provider": "FITBIT",
    "reference_id": "user_12345"
  },
  "status": "authenticated"
}

Disconnection (type: "deauth"):

{
  "type": "deauth",
  "user": {
    "user_id": "terra_abc123",
    "provider": "FITBIT"
  },
  "status": "deauthenticated"
}

Connection Error (type: "connection_error"):

{
  "type": "connection_error",
  "user": {
    "user_id": "terra_abc123",
    "provider": "FITBIT"
  },
  "message": "Token refresh failed"
}

Database Schema Recommendation

CREATE TABLE terra_connections (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),  -- Your user
    terra_user_id VARCHAR(255) UNIQUE,     -- Terra's user ID
    provider VARCHAR(50),                   -- FITBIT, GARMIN, etc.
    reference_id VARCHAR(255),              -- Your reference ID
    connected_at TIMESTAMP DEFAULT NOW(),
    last_sync TIMESTAMP,
    status VARCHAR(20) DEFAULT 'active',    -- active, disconnected
    scopes TEXT[]                           -- Granted permissions
);

CREATE INDEX idx_terra_user ON terra_connections(user_id);
CREATE INDEX idx_terra_reference ON terra_connections(reference_id);

Related Skills

• terra-auth: Authentication and credentials
• terra-data: Retrieve health data
• terra-webhooks: Handle connection events
• terra-sdk: Mobile SDK integration