Core Concepts

Data Stream

The continuous flow of real-time metrics (heart rate, steps, distance, acceleration, and more) from the user's wearable device. The data moves through Terra's system and reaches the developer's backend in real time via a WebSocket connection. As long as the connection is open, the data keeps coming without needing to ask for it again.

Think of it like a pipe, into which multiple producers can pump data, and to which multiple consumers can connect in order to receive that data.

Producer

The producer is the Terra Real-Time (RT) SDK, which reads the wearable's supported data types and sends them to Terra's API. It connects to the wearable using technologies like Bluetooth and ensures the data is constantly transmitted.

Consumer

Your system that receives the data from Terra's API. Once connected, it gets the data in real time and can use it in the app, display it to users, or store it for later use.

Broker

In the context of Terra API, the broker is the intermediary that manages the real-time data stream between producers and consumers.

Terra API acts as the broker by receiving data from producer connections (the RT SDK in your mobile app) and distributing it to consumer connections (e.g., your application's backend).

Authentication tokens

Every WebSocket connection is authenticated with a short-lived token. There are three tokens, all minted from your backend using your Dev ID + API key — never ship those credentials in your app.

Token	Minted from	Used for
SDK (auth) token	POST /auth/generateAuthToken (main API)	Initializing the RT SDK in your app — the token you pass to initConnection.
Producer token	POST /auth/user?id=<user_id> (streaming)	Your app's producer connection — the token you pass to startRealtime(...) to stream the wearable's data to Terra. <user_id> is the streaming user's Terra user_id.
Developer token	POST /auth/developer (streaming)	Your backend's consumer connection — receiving the live stream.

The two streaming tokens (/auth/user and /auth/developer) are single-use and short-lived: each is consumed on the first IDENTIFY (the WebSocket handshake), so mint a fresh one for every connection — and again on every reconnect. The SDK token (generateAuthToken) is reusable for its lifetime; only the streaming tokens are single-use.

If you connect to the WebSocket directly (without an SDK), the producer token pairs with IDENTIFY type 0 (User) and the developer token with type 1 (Developer).

Phone

In the context of this documentation, an Android/iOS device will be referred to as a phone. This will be an iOS or Android phone which connects to a streaming wearable, and sends data to the broker.

You can think of the phone itself as being a producer for all intents and purposes.

Device

For all intents and purposes throughout this documentation, a device will be any wearable capable of streaming supported data types through either a BLE or ANT+ connection.

If the wearable is a Wear OS, Apple Watch, or Samsung wearable (which have a special connection & data streaming process), this will be explicitly made clear.

Data transfer protocols

These are the means by which a device transfers data to a user's phone, and can take one of the following forms.

• Bluetooth Low Energy (BLE) - most popular

• ANT+ - allows one-to-many broadcasting of data

• Custom Bluetooth protocols (Apple Watch, Wear OS, Samsung Watch...)