Ultrahuman Ring API Integration

Need help with your Ultrahuman integration? Pop into our Discord if you have questions or want to discover how Open Wearables can solve your problems.

Overview

Ultrahuman provides access to sleep, recovery, and continuous activity data through their Partnership API. The integration uses OAuth 2.0 for authentication and pull-based syncing to fetch daily metrics.

Supported data types

Data Type	Support
Sleep (with stages)	Yes
Heart rate (24/7)	Yes
HRV - SDNN (24/7)	Yes
Skin temperature (24/7)	Yes
Steps (24/7)	Yes
VO2 max	Yes
Recovery metrics	Partial (normalized, not yet saved)
Workouts / Activities	No (not available via Partnership API)

Data delivery

Method	Description
Polling (pull)	Open Wearables periodically fetches daily metrics via the Ultrahuman Partnership API (default: every hour via Celery Beat)

What you need by the end

App credentials: Client ID + Client Secret from the Ultrahuman Developer Dashboard
OAuth scopes configured
Redirect URI registered

Prerequisites

A personal Ultrahuman account (Ring Air owner)

Application walkthrough

Go to the Ultrahuman Developer Dashboard and sign in with your Ultrahuman account.

Create an OAuth application

In the Developer Dashboard, create a new application:

App Name: Your application name
Redirect URI: Your OAuth callback URL (e.g. http://localhost:8000/api/v1/oauth/ultrahuman/callback for local development)

After creating the app, you’ll receive:

Client ID
Client Secret

Your Client Secret should never be logged or shared. It should only be used server-side.

Configure credentials in Open Wearables

Add the following to your .env file:

#--- Ultrahuman ---#
ULTRAHUMAN_CLIENT_ID=your-ultrahuman-client-id
ULTRAHUMAN_CLIENT_SECRET=your-ultrahuman-client-secret
ULTRAHUMAN_REDIRECT_URI=http://localhost:8000/api/v1/oauth/ultrahuman/callback
ULTRAHUMAN_DEFAULT_SCOPE=ring_data cgm_data profile

Configuration details:

Variable	Description
`ULTRAHUMAN_CLIENT_ID`	Client ID from the Developer Dashboard
`ULTRAHUMAN_CLIENT_SECRET`	Client Secret from the Developer Dashboard
`ULTRAHUMAN_REDIRECT_URI`	Must match the redirect URI registered in the Developer Dashboard. For local dev: `http://localhost:8000/api/v1/oauth/ultrahuman/callback`
`ULTRAHUMAN_DEFAULT_SCOPE`	OAuth scopes requested during authorization

Connect a user via OAuth

With credentials configured and your Open Wearables instance running, initiate the OAuth flow.1. Get the authorization URL:

curl -X GET "http://localhost:8000/api/v1/oauth/ultrahuman/authorize?user_id={user_id}&redirect_uri=http://localhost:3000/users/{user_id}" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

Response:

{
  "authorization_url": "https://auth.ultrahuman.com/authorise?client_id=...&redirect_uri=...&response_type=code&scope=ring_data+cgm_data+profile&state=...",
  "state": "abc123..."
}

2. Redirect the user to the authorization_url. They will log in to Ultrahuman and authorize your app.3. Ultrahuman redirects back to the callback URI configured in your .env. Open Wearables automatically exchanges the authorization code for access and refresh tokens.4. Verify the connection:

curl -X GET "http://localhost:8000/api/v1/users/{user_id}/connections" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

You should see a connection with "provider": "ultrahuman" and "status": "active".

The redirect_uri parameter in the authorize call is where the user is sent after the flow completes (e.g., back to your app). This is separate from ULTRAHUMAN_REDIRECT_URI in your .env, which is the server-side OAuth callback.

Sync data

An initial sync is triggered automatically after a successful OAuth connection. To manually sync:

# Sync all 24/7 data (sleep, HR, HRV, temperature, steps, VO2 max)
curl -X POST "http://localhost:8000/api/v1/providers/ultrahuman/users/{user_id}/sync?data_type=247" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

When no date range is specified, Ultrahuman defaults to syncing the last 30 days of data.

Verify the integration

Once data has synced, fetch it via the Open Wearables API:

# Fetch sleep sessions
curl -X GET "http://localhost:8000/api/v1/users/{user_id}/events/sleep?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

# Fetch timeseries data (HR, HRV, temperature, steps, VO2 max)
curl -X GET "http://localhost:8000/api/v1/users/{user_id}/timeseries?start_time=2026-01-01T00:00:00Z&end_time=2026-02-01T00:00:00Z" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

If data is returned, your Ultrahuman integration is working end-to-end.

API Details

Detail	Value
Auth endpoint	`https://auth.ultrahuman.com/authorise`
Token endpoint	`https://partner.ultrahuman.com/api/partners/oauth/token`
Data API base	`https://partner.ultrahuman.com/api/partners/v1`
Metrics endpoint	`GET /user_data/metrics?date=YYYY-MM-DD`

OAuth Scopes Reference

Scope	Description
`ring_data`	Access to Ring Air data (sleep, HR, HRV, temperature, steps, VO2 max)
`cgm_data`	Access to CGM (continuous glucose monitor) data
`profile`	Access to user profile information

Next Steps

API Reference

Explore the Open Wearables API endpoints.

Coverage Matrix

See the full data coverage comparison.

Support

Need Help?

Join our Discord and ask a question.
Check GitHub Discussions.
Check the Ultrahuman Developer Docs.

Getting started

Architecture

Health Scores

Providers

Rabts Mobile App

Sync SDK

MCP Server

Developer Guides

Configuration

Support

Ultrahuman Ring API Integration

Overview

Supported data types

Data delivery

What you need by the end

Prerequisites

Application walkthrough

API Details

OAuth Scopes Reference

Next Steps

API Reference

Coverage Matrix

Support

​Overview

​Supported data types

​Data delivery

​What you need by the end

​Prerequisites

​Application walkthrough

​API Details

​OAuth Scopes Reference

​Next Steps

API Reference

Coverage Matrix

​Support

Overview

Supported data types

Data delivery

What you need by the end

Prerequisites

Application walkthrough

API Details

OAuth Scopes Reference

Next Steps

Support