Oura Ring API Integration

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

Overview

Oura provides access to sleep, readiness, activity, heart rate, and workout data through the Oura API v2. The integration uses OAuth 2.0 for authentication and supports both pull-based syncing and real-time webhooks - we recommend running Oura in webhook mode for the freshest data.

Supported data types

Data Type	Support
Sleep (with stages)	Yes
Readiness (recovery score)	Yes
Activity (daily activity score)	Yes
Heart rate (24/7)	Yes
SpO2 / breathing disturbance	Yes
VO2 max	Yes
Cardiovascular age	Yes
Workouts / Activities	Yes

Data delivery

Method	Description
Webhooks (push) - recommended	Oura notifies Open Wearables in real time when sleep, readiness, activity, SpO2, or workout data is created or updated. Subscriptions are app-level and are registered automatically when you switch Oura to webhook live-sync mode.
Polling (pull)	Open Wearables periodically fetches daily metrics via the Oura API v2 (default: every hour via Celery Beat)

We recommend running Oura in webhook mode. You get data as soon as Oura finalizes it - typically within seconds instead of up to an hour - with less API traffic and no polling lag. Open Wearables still falls back to periodic pull, so webhooks are purely additive. See Enable webhooks (recommended) in the walkthrough below.

What you need by the end

App credentials: Client ID + Client Secret from the Oura Developer portal
OAuth scopes configured
Redirect URI registered in the Oura Developer portal
Webhook mode enabled (recommended, for real-time updates) - subscriptions are registered automatically

Prerequisites

A personal Oura account (Ring owner)

Application walkthrough

Go to the Oura Developer portal and sign in with your Oura account. Your existing Applications are listed on the Your Applications page.

Create an OAuth application

Click Create New and fill in the New Application form:

Display Name: The name shown to users on the consent screen
Description: A short description of your application
Contact Email: Who Oura can contact about the app
Website: Your application or company URL
Privacy Policy / Terms of Service: URLs to your policy pages
Redirect URIs: Your OAuth callback URL. Open Wearables derives this from your API_BASE_URL as {API_BASE_URL}/api/v1/oauth/oura/callback, so register that exact URL here. Oura requires a publicly accessible HTTPS URL, so plain http://localhost is not accepted - for local development, expose your backend with ngrok and register e.g. https://your-subdomain.ngrok-free.app/api/v1/oauth/oura/callback. In production use your public domain, e.g. https://your-domain/api/v1/oauth/oura/callback.
Scopes: Select the data scopes your app needs (see the OAuth Scopes Reference below)

Tick I agree to the Oura API Agreement, then click Create Application.After creating the app, open it via View Details to retrieve:

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:

# Public base URL of your API. The OAuth redirect URI is derived from this as
# {API_BASE_URL}/api/v1/oauth/oura/callback. For local dev, use your ngrok URL.
API_BASE_URL=https://your-subdomain.ngrok-free.app

#--- Oura ---#
OURA_CLIENT_ID=your-oura-client-id
OURA_CLIENT_SECRET=your-oura-client-secret
OURA_DEFAULT_SCOPE=personal daily heartrate workout session spo2 ring_configuration heart_health
# Token Oura echoes back when verifying your webhook subscription.
# Set a dedicated random value - do not reuse your app SECRET_KEY.
OURA_WEBHOOK_VERIFICATION_TOKEN=your-oura-webhook-verification-token

Configuration details:

Variable	Description
`API_BASE_URL`	Public base URL of your API. The OAuth redirect URI is derived from it as `{API_BASE_URL}/api/v1/oauth/oura/callback`, which must match the redirect URI registered in the Developer portal and must be a public HTTPS URL. For local dev, use your ngrok URL
`OURA_CLIENT_ID`	Client ID from the Developer portal
`OURA_CLIENT_SECRET`	Client Secret from the Developer portal
`OURA_DEFAULT_SCOPE`	OAuth scopes requested during authorization. Must be a subset of the scopes enabled on your application
`OURA_WEBHOOK_VERIFICATION_TOKEN`	Token Oura echoes back when verifying your webhook subscriptions. Set a dedicated random value - do not reuse your app `SECRET_KEY`

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/oura/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://cloud.ouraring.com/oauth/authorize?client_id=...&redirect_uri=...&response_type=code&scope=personal+daily+heartrate+workout+session+spo2+ring_configuration+heart_health&state=...",
  "state": "abc123..."
}

2. Redirect the user to the authorization_url. They will log in to Oura and authorize your app.3. Oura redirects back to the callback URI derived from API_BASE_URL ({API_BASE_URL}/api/v1/oauth/oura/callback). 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": "oura" 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 the server-side OAuth callback ({API_BASE_URL}/api/v1/oauth/oura/callback) that Oura sends the authorization code to.

Enable webhooks (recommended)

We recommend webhooks over polling. They give you real-time updates instead of waiting for the next polling cycle - when Oura records new sleep, readiness, activity, SpO2, or workout data, it immediately notifies Open Wearables, which fetches and saves the record.By default Oura runs in pull (polling) mode. Switching its live-sync mode to webhook registers the subscriptions for you automatically - Open Wearables dispatches a background task that creates a subscription for every supported data type and event type. Make sure OURA_CLIENT_ID, OURA_CLIENT_SECRET, and a public API_BASE_URL are configured first.Switch Oura to webhook mode from the dashboard:In your Open Wearables dashboard, go to Settings → Providers, find Oura, and switch its live-sync control from Periodic pull to Webhook. That’s it - the subscriptions are registered in the background.

Because the callback must be publicly reachable over HTTPS, set API_BASE_URL to your public domain (or your ngrok URL for local development) before switching to webhook mode.

Open Wearables derives the callback URL from your API_BASE_URL as {API_BASE_URL}/api/v1/providers/oura/webhooks, registers a subscription for each data type / event type, and Oura verifies each one using your OURA_WEBHOOK_VERIFICATION_TOKEN. Subscriptions are app-level - they cover all authorized users.Subscribed data types: sleep, daily_sleep, daily_readiness, daily_activity, daily_spo2, daily_cardiovascular_age, workout - each for the create and update events.

Oura subscriptions expire after 90 days and are renewed automatically by a scheduled task (monthly). You can also manage them manually via POST /api/v1/providers/oura/webhooks/subscriptions (register / re-register with a callback_url) and POST /api/v1/providers/oura/webhooks/subscriptions/renew.

Sync data

An initial sync is triggered automatically after a successful OAuth connection. To manually sync or fetch historical data:

# Sync all data types
curl -X POST "http://localhost:8000/api/v1/providers/oura/users/{user_id}/sync?data_type=all" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

You can also sync specific data types:

# Sync only workouts
curl -X POST "http://localhost:8000/api/v1/providers/oura/users/{user_id}/sync?data_type=workouts" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

# Sync only 24/7 data (sleep, readiness, activity, heart rate, SpO2)
curl -X POST "http://localhost:8000/api/v1/providers/oura/users/{user_id}/sync?data_type=247" \
  -H "X-Open-Wearables-API-Key: YOUR_API_KEY"

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 (heart rate, SpO2, activity, VO2 max, cardiovascular age)
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 Oura integration is working end-to-end.

API Details

Detail	Value
Auth endpoint	`https://cloud.ouraring.com/oauth/authorize`
Token endpoint	`https://api.ouraring.com/oauth/token`
Revoke endpoint	`https://api.ouraring.com/oauth/revoke`
Data API base	`https://api.ouraring.com/v2/usercollection`
Webhook callback	`POST /api/v1/providers/oura/webhooks`

OAuth Scopes Reference

Scope	Description
`email`	User’s email address
`personal`	Personal information (age, biological sex, height, weight)
`daily`	Daily summaries - sleep, readiness, and activity scores
`heartrate`	24/7 heart rate data
`workout`	Workout / activity sessions
`tag`	User-entered tags
`session`	Guided and unguided sessions (e.g. moment, breathing)
`spo2`	Blood oxygen (SpO2) and breathing disturbance data
`ring_configuration`	Ring hardware configuration
`stress`	Daily stress data
`heart_health`	Cardiovascular age and VO2 max

The scopes requested by Open Wearables are controlled by OURA_DEFAULT_SCOPE and must be a subset of the scopes enabled on your application in the Developer portal.

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 Oura API Docs.

Getting started

Architecture

Health Scores

Providers

Rabts Mobile App

Sync SDK

MCP Server

Developer Guides

Configuration

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

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