terra-auth

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.

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Fix and improve this skill with Tessl

tessl review fix ./skills/terra-auth/SKILL.md

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
client = Terra(
    dev_id="botaniqalmedtech-testing-SjyfjtG33s",
    api_key="_W7Pm-kAaIf1GA_Se21NnzCaFZjg3Izc"
)

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

Environment Variables

# .env.testing
TERRA_DEV_ID=botaniqalmedtech-testing-SjyfjtG33s
TERRA_API_KEY=_W7Pm-kAaIf1GA_Se21NnzCaFZjg3Izc

# .env.staging
TERRA_DEV_ID=botaniqalmedtech-staging-uGKHOPRCi1
TERRA_API_KEY=fJia30spa-EqB_CMqZBzzrkMWZ_u2pv_

# .env.production
TERRA_DEV_ID=botaniqalmedtech-prod-yrc99AwsT2
TERRA_API_KEY=Il4YUTc-e00EcvKGUx63j7YE3MJ-7QIz

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": "botaniqalmedtech-testing-SjyfjtG33s",
            "api_key": "_W7Pm-kAaIf1GA_Se21NnzCaFZjg3Izc"
        },
        "staging": {
            "dev_id": "botaniqalmedtech-staging-uGKHOPRCi1",
            "api_key": "fJia30spa-EqB_CMqZBzzrkMWZ_u2pv_"
        },
        "production": {
            "dev_id": "botaniqalmedtech-prod-yrc99AwsT2",
            "api_key": "Il4YUTc-e00EcvKGUx63j7YE3MJ-7QIz"
        }
    }

    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: botaniqalmedtech-testing-SjyfjtG33s" \
  -H "x-api-key: _W7Pm-kAaIf1GA_Se21NnzCaFZjg3Izc"

Security Best Practices

Never expose API keys in frontend/mobile apps
Use environment variables for credentials
Generate mobile tokens on backend only
Use HTTPS for all redirect URLs
Rotate keys if compromised (contact Terra support)
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

Repository: fernandezbaptiste/Skrillz
Path: skills/terra-auth/SKILL.md
Commit: 93ed392

Last updated: 1 day ago
First committed: 8 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.