terra-auth

name	terra-auth
description	Terra API authentication, credentials management, and environment configuration. Use when setting up Terra integration, managing API keys, generating widget sessions, or configuring testing/staging/production environments.

Terra Authentication & Credentials

Manage Terra API authentication across testing, staging, and production environments.

Credential Files

Credentials are stored in environment-specific .env files:

Environment	File
Testing	.env.terra.testing
Staging	.env.terra.staging
Production	.env.terra.production

Load credentials:

from dotenv import load_dotenv
import os

# Load specific environment
load_dotenv(".env.terra.testing")

dev_id = os.getenv("TERRA_DEV_ID")
api_key = os.getenv("TERRA_API_KEY")

Or use the helper:

from scripts.terra_client import get_terra_client

client = get_terra_client("testing")  # or "staging", "production"

Quick Start

Python SDK Setup

from terra import Terra

# Testing environment - load from .env.terra.testing
client = Terra(
    dev_id=os.environ["TERRA_DEV_ID"],
    api_key=os.environ["TERRA_API_KEY"]
)

# Verify connection
integrations = client.integrations.fetch()
print(f"Connected! {len(integrations.integrations)} providers available")

Environment Variables

# .env.testing
TERRA_DEV_ID=your-dev-id-here
TERRA_API_KEY=your-api-key-here

# .env.staging
TERRA_DEV_ID=your-staging-dev-id
TERRA_API_KEY=your-staging-api-key

# .env.production
TERRA_DEV_ID=your-production-dev-id
TERRA_API_KEY=your-production-api-key

Operations

setup-environment

Configure Terra credentials for specific environment.

Python:

import os
from terra import Terra

def get_terra_client(env: str = "testing") -> Terra:
    """Get Terra client for specified environment."""
    configs = {
        "testing": {
            "dev_id": os.environ.get("TERRA_DEV_ID_TESTING"),
            "api_key": os.environ.get("TERRA_API_KEY_TESTING")
        },
        "staging": {
            "dev_id": os.environ.get("TERRA_DEV_ID_STAGING"),
            "api_key": os.environ.get("TERRA_API_KEY_STAGING")
        },
        "production": {
            "dev_id": os.environ.get("TERRA_DEV_ID_PRODUCTION"),
            "api_key": os.environ.get("TERRA_API_KEY_PRODUCTION")
        }
    }

    config = configs.get(env)
    if not config:
        raise ValueError(f"Unknown environment: {env}")

    return Terra(dev_id=config["dev_id"], api_key=config["api_key"])

# Usage
client = get_terra_client("testing")

generate-widget-session

Create authentication widget URL for end users.

Python:

def generate_widget_session(
    client: Terra,
    reference_id: str,
    success_url: str,
    failure_url: str,
    providers: list[str] = None
) -> str:
    """Generate widget session URL for user authentication."""

    response = client.authentication.generatewidgetsession(
        reference_id=reference_id,
        auth_success_redirect_url=success_url,
        auth_failure_redirect_url=failure_url,
        providers=providers  # Optional: filter providers ["FITBIT", "GARMIN"]
    )

    return response.url

# Usage
widget_url = generate_widget_session(
    client=client,
    reference_id="user_12345",  # Your internal user ID
    success_url="https://app.botaniqal.com/terra/success",
    failure_url="https://app.botaniqal.com/terra/failure"
)
print(f"Redirect user to: {widget_url}")

Response:

{
  "url": "https://widget.tryterra.co/session/abc123...",
  "session_id": "abc123...",
  "expires_at": "2025-12-05T12:15:00Z"
}

generate-mobile-token

Generate authentication token for mobile SDK.

Python:

def generate_mobile_token(client: Terra) -> str:
    """Generate token for mobile SDK initialization.

    Note: Token is generated for the account, not per-user.
    Use reference_id in the mobile SDK init to identify users.
    """
    response = client.authentication.generateauthtoken()
    return response.token

# Usage (backend endpoint)
@app.route("/api/terra/mobile-token", methods=["POST"])
@login_required
def get_mobile_token():
    token = generate_mobile_token(client=terra_client)
    # Pass reference_id to mobile SDK, not to token generation
    return jsonify({
        "token": token,
        "reference_id": str(current_user.id)  # For SDK init
    })

Token Expiration: 180 seconds (3 minutes), one-time use.

deauthenticate-user

Remove user and revoke data access.

Python:

def deauthenticate_user(client: Terra, user_id: str) -> bool:
    """Deauthenticate user and remove their data."""

    response = client.authentication.deauthenticateuser(user_id=user_id)
    return response.success

# Usage
success = deauthenticate_user(client, "terra_user_abc123")
if success:
    print("User deauthenticated successfully")

list-integrations

Get all available provider integrations.

Python:

def list_integrations(client: Terra) -> list:
    """List all available Terra integrations."""

    response = client.integrations.fetch()

    integrations = []
    for integration in response.integrations:
        integrations.append({
            "name": integration.name,
            "resource": integration.resource,
            "logo_url": integration.logo_url
        })

    return integrations

# Usage
providers = list_integrations(client)
for p in providers:
    print(f"{p['name']}: {p['resource']}")

REST API Headers

All REST API calls require these headers:

dev-id: <YOUR_DEV_ID>
x-api-key: <YOUR_API_KEY>
Content-Type: application/json

cURL Example:

curl -X GET "https://api.tryterra.co/v2/integrations" \
  -H "dev-id: $TERRA_DEV_ID" \
  -H "x-api-key: $TERRA_API_KEY"

Security Best Practices

1. Never expose API keys in frontend/mobile apps
2. Use environment variables for credentials
3. Generate mobile tokens on backend only
4. Use HTTPS for all redirect URLs
5. Rotate keys if compromised (contact Terra support)
6. Different keys per environment (testing/staging/production)

Webhook Signing Secret

Each environment has a unique signing secret for webhook verification:

• Found in Terra Dashboard → Destinations → Webhooks
• Used for HMAC-SHA256 signature verification
• See terra-webhooks skill for implementation

Session Lifecycle

Token Type	Expiration	Notes
Widget Session	15 minutes	URL valid until used or expired
Mobile SDK Token	3 minutes	One-time use, generate per connection
OAuth Tokens	Auto-refresh	Terra manages automatically
API Keys	Never	Rotate manually if needed

API Base URLs

Environment	Base URL
Production API	https://api.tryterra.co
Widget	https://widget.tryterra.co
Streaming	wss://streaming.tryterra.co

Related Skills

• terra-connections: Connect users to wearables
• terra-data: Retrieve health data
• terra-webhooks: Handle real-time events
• terra-sdk: SDK integration patterns