Skip to main content

​
Overview

The Developer Portal is a comprehensive web-based dashboard that allows you to manage your Open Wearables integration without writing code. Access user data, monitor connections, manage API credentials, and configure provider settings all from a single interface.
The portal is automatically available at http://localhost:3000 when running Open Wearables with Docker Compose.

​
Getting Started

​
Initial Login

An admin account is automatically created on first startup using environment variables: 
ADMIN_EMAIL=[email protected]       # Default email
ADMIN_PASSWORD=your-secure-password  # Default password
You can customize these credentials in your backend/config/.env file before starting the application.

​
Access Points

Once running, the portal provides these entry points:

Dashboard

View statistics, recent users, and data metrics

Users

Manage users and view detailed health data

Settings

Configure API keys, providers, and team access

API Docs

Interactive Swagger documentation

​
Dashboard Overview

The dashboard provides at-a-glance insights into your platform usage:

​
Key Metrics

  • Total Users: Current number of registered users
  • Active Connections: Number of active provider connections
  • Data Points: Total health data records synced
  • Recent Activity: Latest user registrations and data syncs

​
Data Metrics Section

Explore your platform’s data distribution:
  • Top Series Types: Most frequently synced health data types (heart rate, steps, sleep, etc.)
  • Popular Workout Types: Most common workout activities from connected devices

​
Recent Users

View the latest user registrations with:
  • User names and email addresses
  • Registration dates
  • Connected provider status
  • Quick navigation to user detail pages

​
User Management

​
Creating Users

You can add users through multiple methods:
  1. Navigate to the Users section
  2. Click Add User
  3. Fill in user details:
    • Email address (required)
    • First and last name (optional)
  4. Click Create User
The user will receive an invitation email to set their password.

​
User Detail View

Click any user to see comprehensive information:
  • Full name and email
  • Registration date
  • User ID for API integration
  • Edit profile dialog
  • Connected provider badges
  • Weight tracking over time
  • BMI calculations
  • Body fat percentage
  • Period toggles (7/30/90 days)
  • Visual charts with trend lines
  • Daily step counts
  • Active minutes
  • Calories burned
  • Distance traveled
  • Interactive chart selection
  • Sleep duration and quality
  • Sleep stages (deep, light, REM)
  • Sleep sessions timeline
  • Weekly patterns
  • Complete workout list with pagination
  • Workout type and duration
  • Heart rate time series
  • Source provider badge
  • Detailed metrics per workout
  • Connection status for each provider
  • Last sync timestamp
  • Manual sync trigger
  • Disconnect option

​
Users Table Features

  • Search: Filter users by name or email
  • Sorting: Sort by name, email, or registration date
  • Pagination: Navigate through large user lists
  • Bulk Actions: Select multiple users for operations
  • Quick Actions: Edit, view details, or delete users

​
Settings

The Settings section provides configuration options across multiple tabs:

​
Credentials Tab

Manage API authentication:
1

Create API Key

Click Create API Key and provide a descriptive name
2

Copy Key

The key is displayed immediately - copy it securely
3

Use in Requests

Include the key in all API requests:
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8000/api/v1/users
API keys are shown in full only once after creation. Store them securely - they cannot be retrieved later.
Key Management Features:
  • View all active API keys
  • Toggle key visibility (masked by default)
  • Copy keys to clipboard
  • Delete revoked keys
  • See creation timestamps

​
Providers Tab

Configure OAuth provider availability: 
// Available providers
- Garmin (OAuth 1.0)
- Polar (OAuth 2.0)
- Suunto (OAuth 2.0)
- Strava (OAuth 2.0)
- Whoop (OAuth 2.0)
Configuration Options:
  • Enable/disable individual providers
  • View provider status (cloud vs SDK-based)
  • Save changes to apply immediately
  • Provider icons and display names
Only enabled providers will appear in the connection widget and OAuth flows for end users.

​
Priorities Tab

Set data source priorities when multiple providers supply the same metric:
  • Drag and drop to reorder providers
  • Higher priority sources override lower ones
  • Applies to overlapping time ranges
  • Per-metric configuration (heart rate, steps, etc.)

​
Team Tab

Manage developer access to the portal:
  • Invite team members via email
  • Assign roles (Admin, Developer, Viewer)
  • Revoke access when needed
  • View active sessions

​
Technical Implementation

The portal is built with modern web technologies: 
// Stack
Frontend: React 19 + TypeScript
Routing: TanStack Router (file-based)
State: TanStack Query (server state)
Forms: React Hook Form + Zod
UI: Tailwind CSS 4.0 + shadcn/ui
Charts: Recharts

​
Authentication Flow

The portal uses JWT-based authentication:
  1. User logs in with email/password
  2. Backend issues JWT access token
  3. Token stored in browser localStorage
  4. All API requests include Authorization header
  5. Token expires after configured duration
  6. Automatic redirect to login on 401 responses
Session Management: 
// frontend/src/lib/auth/session.ts
import { getToken, clearSession } from '@/lib/auth/session';

// Check authentication
const isAuthenticated = () => {
  return !!getToken();
};

// Logout
const logout = () => {
  clearSession();
  window.location.href = '/login';
};

​
Protected Routes

All authenticated pages use route guards: 
// frontend/src/routes/_authenticated.tsx
export const Route = createFileRoute('/_authenticated')({
  component: AuthenticatedLayout,
  beforeLoad: () => {
    if (!isAuthenticated()) {
      throw redirect({ to: '/login' });
    }
  },
});

​
Mobile Access

The developer portal is fully responsive and works on mobile devices:
  • Touch-optimized navigation
  • Adaptive layouts for small screens
  • Mobile-friendly charts and tables
  • Gesture support for swipe actions

​
Performance Optimizations

Data Caching

TanStack Query caches API responses to minimize network requests

Lazy Loading

Components load on-demand for faster initial page loads

Optimistic Updates

UI updates immediately while API calls process in background

Virtual Scrolling

Large tables render only visible rows for smooth scrolling

​
Next Steps

Unified API

Learn how to access user data programmatically

OAuth Flow

Set up provider connections for your users

Build docs developers (and LLMs) love

Get started for freeTalk to us