> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/streaming-api/core-concepts.md).

# 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](#producer) can pump data, and to which multiple [consumers](#consumer) 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](/reference/streaming-api/websocket-reference.md#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](#producer) (the RT SDK in your mobile app) and distributing it to [consumer connections](#consumer) (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](#broker).

You can think of the phone itself as being a [producer](#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](/reference/streaming-api/websocket-reference.md#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](#device) transfers data to a user's [phone](#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...)