> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect wearables & view data
> Step-by-step guide to sign in, connect a wearable OAuth integration, and inspect imported session data in the Synheart Platform
This guide walks through the primary workflow on [`platform.synheart.ai`](https://platform.synheart.ai): sign in, set your organization and tenant context, connect a third-party wearable to a registered app, and explore the session data that flows in.
Each step covers what to do in the UI, what you should see, and what the results mean. Use this page after you have completed [Create a platform account](/setup/create-account) and registered at least one [app](/platform/developer-portal#register-an-app) inside a [project](/platform/projects).
The platform is **invite-only** today. If you do not have access yet, [request an invite](https://synheart.ai/work-with-us) before starting.
## At a glance
```text theme={null}
Sign in → select organization & tenant → open a project → connect a wearable → browse sessions → open session detail
```
| Step | Outcome |
| ----- | --------------------------------------------------------- |
| **1** | Workspace context set; a project is open |
| **2** | Wearable integration created and moving toward **Active** |
| **3** | Imported sessions visible in the explorer |
| **4** | Snapshot payload inspected |
**Prerequisites**
* An **organization** with at least one **tenant**, **project**, and registered **app**.
* OAuth credentials from your wearable vendor (WHOOP, Garmin, Fitbit, and others in the vendor catalog) when configuring a cloud integration.
* An [API key](/platform/api-keys) with **ingestion allowlisting** if your app sends on-device HSI snapshots; this path is separate from vendor OAuth.
Keep the **organization** and **tenant** selectors correct before debugging empty lists. Most project-scoped pages require both to be set.
***
## Step 1: Sign in and set workspace context
**Goal:** Authenticate, scope the dashboard to the right organization and tenant, and open the project you want to work in.
### 1.1 Sign in
1. Open [`platform.synheart.ai`](https://platform.synheart.ai).
2. Complete sign-in when prompted. Supported methods:
* **Email** and **Password**
* **Continue with Google**
* **Continue with GitHub**
3. If multi-factor authentication (MFA) is enabled on your account, enter your **6-digit TOTP code** on the **Two-factor authentication** screen (or use a recovery code).
**What you see:** After a successful login, you land on **Projects** (`/projects`) unless you arrived via an invitation or deep link.
### 1.2 Select organization and tenant
In the **left sidebar**, use the two switchers above the navigation links:
1. **Organization switcher**: dropdown header **Organizations**. Pick the company account that owns your projects.
2. **Tenant switcher**: dropdown header **Tenants**. Pick the workspace (tenant) that contains the project.
**What you see:** Project lists, wearables, and sessions load for the selected pair. If no tenant exists yet, you may see **No tenant yet** with a **Create your first tenant** action on **Projects**.
**What you do if blocked:** Create a tenant at **Tenants** (`/tenants`) or ask an organization administrator to invite you to one.
Wearables and sessions wait for a valid **organization + tenant** pair. Without a tenant, lists stay empty and you may see messages such as *"Create a tenant for this organization to load wearables."* or *"Select a workspace (tenant) to load project API keys."*
### 1.3 Open a project
1. From **Projects** (`/projects`), click a project card.
2. Confirm the **Overview** page loads at `/projects/{projectId}`.
**What you see:** The sidebar switches to **Project** navigation with the following items:
| Sidebar item | Purpose |
| -------------------- | ------------------------------- |
| **All projects** | Return to the project list |
| **Overview** | KPI cards and trend charts |
| **Sessions** | Project-wide session explorer |
| **Apps** | Registered apps in the project |
| **Wearables** | Project-wide wearable OAuth hub |
| **API Keys** | Project-scoped key management |
| **Studies** | Research studies (when enabled) |
| **Project settings** | Rename, archive, data purge |
***
## Step 2: Connect a wearable integration
**Goal:** Register an OAuth integration between a platform app and a vendor API so biosignals can flow in once the integration is **Active**.
Wearable connections are **OAuth integrations**: one row per **vendor × app**. The platform stores encrypted credentials and scopes; your mobile app or vendor webhooks deliver data after setup completes.
### 2.1 Choose where to manage wearables
You can manage wearables from two equivalent surfaces:
| Surface | When to use |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| **Project → Wearables** | See every vendor × app row across all apps in the project. Open from the project sidebar. |
| **App → Wearables** | Manage wearables in the context of a single app. Open from the app sidebar. |
Both surfaces open the same **Add Wearable** / **Edit Wearable** drawer.
### 2.2 Review hub KPIs
On **Wearables**, four summary cards appear at the top:
| KPI | Description |
| ---------------- | -------------------------------------------------------------------------------- |
| **Wearables** | Count of integration rows (vendor × app) in the project |
| **Vendor types** | Distinct vendors connected; the link shows how many are available in the catalog |
| **Active** | Integrations that are ready for data |
| **Needs setup** | Integrations that are pending or have missing credentials |
### 2.3 Start the setup wizard
1. On **Wearables**, click **Setup new wearable**.
* The button is **disabled** until the project has at least one app; register an app under **Apps** first.
2. In the **Add Wearable** drawer, complete the form:
| Form field | Description |
| -------------------- | ----------------------------------------------------------------- |
| **App** | Registered app that owns this vendor connection |
| **Device Type** | Vendor from the active catalog |
| **Client ID** | OAuth client ID from the vendor developer portal |
| **Client Secret** | OAuth client secret (never shown again after save) |
| **App Redirect URI** | OAuth callback URL registered with the vendor |
| **Scopes** | Permission keys for this vendor; required scopes are pre-selected |
3. Submit the form.
**What you see on success:** The drawer shows **Integration created** with optional **Webhook URLs**, a **Provider Portal** link, and **Setup Notes** with vendor-specific instructions.
#### Integration status labels
| Status | Action button |
| ------------------ | ------------------ |
| **Active** | **Edit Wearable** |
| **Pending** | **Continue setup** |
| **Not configured** | **Setup Wearable** |
Each app supports **one integration per vendor type**. If **Device Type** has no options, every catalog vendor may already be connected for that app; use **Edit Wearable** on an existing row instead.
### 2.4 Finish vendor-side setup
1. Copy any **Webhook URLs** from the success panel into the vendor developer portal.
2. Open the **Provider Portal** link and complete redirect URI registration, webhook endpoints, and user authorization as required.
3. Return to the platform and confirm the row shows **Active**.
**Data import timing:**
* **Webhook-driven vendors**: biosignals arrive when the vendor POSTs to Synheart webhook URLs.
* **On-device SDK path**: sessions appear after your app ingests HSI snapshots with an [allowlisted API key](/platform/api-keys#ingestion-access), independent of OAuth status in the wearables list.
#### Filter the wearables list
| Filter | Effect |
| --------------- | -------------------------------------------- |
| **All Apps** | Show integrations for a specific app |
| **All Vendors** | Show integrations for a specific vendor type |
***
## Step 3: View imported session data
**Goal:** Confirm data is ingesting and locate individual snapshots in the project **Sessions** explorer.
### 3.1 Open the session explorer
1. In the project sidebar, click **Sessions** (`/projects/{projectId}/sessions`).
2. Confirm the page title **Sessions** and subtitle `{project name} · Session explorer`.
**Default date range:** **30D** (last 30 days). KPI comparison labels adapt to the preset (e.g. **vs yesterday**, **vs last week**, **vs last month**).
### 3.2 Read KPI cards
| KPI | Description |
| --------------------------- | ---------------------------------------------------------- |
| **Total sessions** | Number of sessions in the selected date range |
| **Avg Valence Confidence** | Average valence confidence score across filtered sessions |
| **Avg Capacity Confidence** | Average capacity confidence score across filtered sessions |
| **Avg Arousal Confidence** | Average arousal confidence score across filtered sessions |
Each card shows a period-over-period delta based on the selected date range.
### 3.3 Filter and search
| Control | Effect |
| -------------------------- | ------------------------------------------------------------------------------------- |
| Search box | Matches snapshot ID, app/producer label, wearable label, emotion, and activity |
| **All / Lab / HSI** | **Lab** shows lab warehouse sessions; **HSI** shows on-device SDK ingests |
| **1D / 7D / 30D / Custom** | Rolling or custom date window |
| **All apps** | Restrict to one registered app |
| **All wearables** | Restrict to sessions from a linked wearable device type |
| **Export** | Downloads a CSV containing Snapshot ID, Observed, Producer · App, Source, and Windows |
If the table is empty, widen the range to **30D** or **Custom**, confirm ingestion allowlisting for HSI data, and verify the correct **organization** and **tenant** are selected.
### 3.4 Session list columns
| Column | Meaning |
| ------------------ | --------------------------------------------------------------- |
| **Snapshot ID** | Unique identifier for the session; click to open session detail |
| **Created At** | When the record was stored in the platform |
| **Observed** | When the snapshot was observed on device |
| **Producer · App** | Which app produced the snapshot and which device instance |
| **Source** | **HSI** or **Lab** badge indicating the ingestion source |
| **Windows** | Number of time windows in the session |
***
## Step 4: Inspect a single session
**Goal:** Open one snapshot, review structured fields and charts, and export the raw JSON if needed.
### 4.1 Open session detail
1. In the sessions table, click a **Snapshot ID**.
2. The detail page opens at `/projects/{projectId}/sessions/{sessionRef}?source=…`.
**What you see:**
* Page title **Session detail**
* Subtitle: *Snapshot payload, axes, and related metrics for this session.*
* **Export JSON** button (top right)
* **Snapshot detail** section: a view-descriptor-driven layout rendered from the payload
### 4.2 Export the payload
1. Click **Export JSON**.
2. A file named `session-{sessionId}.json` downloads.
**What is included:** The full session record in its native JSON format. Internal infrastructure fields are omitted from the download.
### 4.3 Understand the Snapshot detail view
The **Snapshot detail** section uses a backend **view descriptor** to render tables, stat cards, and charts dynamically. Depending on HSI schema version and payload shape, you may see:
| Section type | Typical content |
| ------------------------- | -------------------------------------------- |
| Stat / key-value panels | Session metadata, app context, timing |
| Axis tables or cards | HSI axes by domain (cognitive, affective, …) |
| Line / bar / radar charts | Time-series or aggregate metrics |
| Enum-labeled fields | Dominant emotion, activity state |
Older snapshots may show fewer sections if axes or biosignals were not captured. Use **Export JSON** to inspect the full payload when a field appears missing in the UI.
#### Biosignal fields (when present in payload)
| Signal | Description | Update cadence |
| ---------------- | ---------------------- | ----------------------- |
| Heart rate | Beats per minute | Per biosignal timestamp |
| HRV (SDNN) | Heart rate variability | Per timestamp |
| Respiratory rate | Breaths per minute | Per timestamp |
| Blood oxygen | SpO₂ percentage | Per timestamp |
| Temperature | Skin/body temperature | Per timestamp |
***
## Reference: project overview KPIs
The **Overview** page (`/projects/{projectId}`) shows complementary aggregates for the selected **1D / 7D / 30D / Custom** range. Use it for trends; use **Sessions** for row-level inspection.
| KPI | Description |
| ----------------------- | --------------------------------------------------- |
| **Total Subjects** | Distinct users with snapshots in the selected range |
| **Average Valence** | Average valence axis score for the period |
| **Average Capacity** | Average cognitive capacity axis score (0–1) |
| **Average Arousal** | Average affective arousal axis score |
| **Average Sleep** | Average sleep axis value |
| Valence–arousal scatter | One point per snapshot in range |
***
## Troubleshooting
| Symptom | Likely cause | What to check |
| ------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Wearables list empty | No tenant selected | Create or select a tenant in the sidebar switcher |
| **Setup new wearable** disabled | Project has no apps | Register an app under **Apps** first |
| Integration stuck **Pending** | Vendor OAuth not finished | Open **Continue setup**; follow **Provider Portal** link |
| Sessions list empty | No data in date range, or ingestion not allowlisted | Widen **30D** range; confirm [API key ingestion access](/platform/api-keys#ingestion-access) |
| Session detail missing sections | Snapshot predates current HSI schema or lacks axes | Check **Source** badge; **Export JSON** to inspect raw payload |
| **Lab** vs **HSI** confusion | Different ingestion pipelines | **HSI** = SDK/runtime snapshots; **Lab** = lab warehouse imports |
| Session not found on detail | Wrong org/tenant or invalid ID | Confirm sidebar context; verify the Snapshot ID from the list |
See also [Troubleshooting](/guides/troubleshooting) and [Projects](/platform/projects).
***
## Next steps
Create projects, add apps, and understand the resource hierarchy.
Issue keys and request ingestion allowlisting for on-device data.
Learn how device adapters capture biosignals on mobile and watch.
See how sessions are produced before they appear in the platform.