Oura Ring v2 Custom Integration - Track Your Sleep, Readiness & Activity in Home Assistant💍

[louisp (Louis)]

Hi everyone! I’m excited to share my new custom integration for the Oura Ring Gen 4 that I’ve been working on.

What is it?

A modern Home Assistant integration for Oura Ring using the official v2 API with OAuth2 authentication. It brings all your Oura health data directly into Home Assistant with 30 sensors covering sleep, readiness, activity, heart rate, and HRV.

GitHub: GitHub - louispires/oura-v2-custom-component: Modern Home Assistant integration for Oura Ring using v2 API with OAuth2 authentication

HACS Installation (Recommended)

Oura Ring is now available in the HACS default repository!

1. Open HACS in your Home Assistant instance
2. Click on “Integrations”
3. Search for “Oura Ring”
4. Click “Download”
5. Restart Home Assistant

Add Integration to Home Assistant

Click the button above to add the Oura Ring integration to your Home Assistant instance.

Why Another Oura Integration?

• Modern OAuth2 authentication - Uses HA’s built-in Application Credentials (no manual token copying!)

• Latest API v2 - Full support for Oura’s current API endpoints

• 43 comprehensive sensors - Sleep stages, HRV, heart rate, activity metrics

• HACS compatible - Easy installation and updates

• Configurable polling - Set your own update interval (1-60 minutes)

• Built with modern HA standards - DataUpdateCoordinator, async operations, proper typing

[louisp (Louis)]

There are 2 outstanding issues/PRs:

Add Oura brand icons to Home Assistant Brands repository by louispires · Pull Request #8280 · home-assistant/brands
Adds new integration [louispires/oura-v2-custom-component] by louispires · Pull Request #4481 · hacs/default

These are needed for the icons and to be listed under HACS by default.

However, the do not prevent you from manually installing the integration for now

[willis-63]

I literally quit installing a fork of the original repo earlier today after seeing Oura’s API v1 deprecation note… your timing could not have been better.

After changing my redirect URI from the one given in the original installation doc, to option B in the Fixing-Redirect-URI doc, the HA redirect upon adding the integration worked properly with my local instance. I’ve got sensors loaded in and displaying correctly! Thank you for your work!

[louisp (Louis)]

Glad it worked for you, and you were able to resolve the issue with documentation.

It will take a couple of days for your Data to start looking better on the Dashboards, but if you have any issues or requests, don’t hesitate to let me know

[willis-63]

Any idea why the entities wouldn’t be updating automatically? I manually reloaded the integration this morning by changing the query time from 5min to 6min, just to grab proper readings. As I’ve left it alone, though, the entities aren’t updating themselves. I’ve been monitoring the current heart rate entity as it has the most variable data, and it’s gone for 2 hours now without updating according to the entity page. Still displaying the reading from 2 hours ago. Is this user error?

Edit: I’ve since updated to repo v1.1 and I was unable to pre-load the old data, while the entities are still not updating automatically. I uninstalled and reinstalled the repository from HACS to allow for your first-time installation configuration. Let me know if you need logs or further description, happy to help!

[louisp (Louis)]

Unfortunately the API really doesnt seem to be Realtime, I will check if we can get the heartrate to be more realtime than it currently is.

Also remember, you must still open your Oura app for the data to sync with your phone and Oura servers.

Then wait 5 minutes for the API to pull the data.

The new V1.1 is Unfortunately not as straight forward as just seeing historical data on the normal Sensors.

But if you look at the statistics, you will see new entries created and all the historical data lives there.

I created some Dashboards to visualize the data, will share them in a couple of hours as they are on my Test HA.

Ultimately, the best is to just wait and the data will trickle in over a couple of days.

[louisp (Louis)]

@willis-63 I just adjusted my integration to 1 minute.

Then opened my Oura app and forced a heart rate measurement.

Then went to look at HA and within a minute, my reading was there:

Please try doing the same and let me know?

[willis-63]

So the heart rate specifically isn’t a sticking point for me, it just best visualizes my problem. The behavior is true of all entities. Even with the integration set to pull from the API every minute, it only seems to update if I manually reload the integration. The changes in my history graph here occur when I reload the integration or restart home assistant. None of the entities update themselves like yours seem to display in the pictures.

I will continue to let data build though and see what happens !

[louisp (Louis)]

Okay that is very strange - Can you kindly provide me with some logs.

1. Enable Debug Logging on the Integration
2. Reload the Integration
3. Wait 2 minutes (Since your integration is set to 1 minute)
4. Disable Debug Logging
5. Log File will be downloaded

Simply upload the file content on here or upload the file to some file sharing service like WeTransfer.

Inside the log files you will see entries for:

• custom_components.oura
• custom_components.oura.api
• custom_components.oura.statistics
• custom_components.oura.coordinator

Debug and Info are normal, any errors would be useful to see

[willis-63]

I can upload the full log if needed, but I don’t see any notable errors. I actually see data in the logs. It seems to be behaving as it should. They even show successful grabbing of historical data, and successful recurring pings of the API. But as you saw in my previous screenshot, the sensors will go up to “4 hours ago” or “8 hours ago.”

I did notice that for whatever reason my API in general does not update as quickly as yours and I can’t quite explain that. I say this because even after forcing a heart rate reading in the Oura app, waiting 5min, and manually reloading the integration, my heart rate doesn’t change which would suggest the data in my cloud account hadn’t updated yet.

Edit: I checked again when I got home. It appears the sensors reloaded once on their own while I was out. I wonder if my API experience is just egregiously slow, as they seem to update when there is new information to grab.

[louisp (Louis)]

That is indeed very strange - Not seeing any errors.

Please can you also try adding this card to your Dashboard:

type: statistics-graph
title: Activity Metrics
entities:
  - oura:average_heart_rate
  - oura:max_heart_rate
  - oura:min_heart_rate
days_to_show: 14
chart_type: bar

This should then show your entries for Historical Data.

Please confirm which Generation ring you have?

[willis-63]

Looks like all the historical data is loaded in correctly!

My ring is a Gen3, I’ve attempted to research any differences in how it might affect API updates compared to your Gen4 and haven’t come across anything notable.

I have made a point in the past few days to open the Oura app on my phone a few times a day, especially in the morning. What I’ve found is that the entities are in fact updating themselves when there is something to update, it just seems some statistics are slower to update in the cloud for me… current heart rate for instance. When I wake up and open the app, typically my sleep data will appear in Home Assistant within 10min, which is the expected behavior. Other entities will simply not update within the cloud for upwards of 4-8 hours, leading to extended periods of time where the Home Assistant sensors would time out like I saw.

In short, it seems your integration is behaving as expected and whatever issue I may have has more to do with API updates within the Oura app.

[louisp (Louis)]

That is good to hear.

Do you perhaps have a Legacy Oura subscription? Thos grandfathered Lifetime Memberships?

This is the only thing I can think of, that those accounts are on slower servers and not as granular as the normal subscriptions.

I only joined the Oura system just over 2 weeks ago with the Gen 4.

Also doubt that the ring makes a difference in the API though, but perhaps the subscription…

[willis-63]

Buying a ring and building an integration with oauth2 in 2 weeks is impressive work, again, thank you for sharing this project!

Unfortunately that’s not the answer in my case. I’m a regular subscriber, currently on the monthly payment plan. I have collected some extra information though. I’ve found that my Oura cloud account seems to reflect a day-time sync about 40-50min after it’s completed on the app. However, even with forcing a heart rate reading, that sync did not include any heart rate information for the time period between the last sync and this one. I’ve attached screenshots from my cloud account, rather than the app.

The only way I can make sense of that would be a data packaging difference between the Gen3 and Gen4, where the Gen3 simply does not consider the heart rate entity “high priority” enough to update the cloud. Maybe the smart sensing feature in the Gen4 includes tags in the payloads that allow for a more consistent uploads to the cloud, while the Gen3 relies on longer, less-complete batch uploads? I only say this because my sleep readings are instantaneously uploaded to the cloud in the morning, suggesting some data payloads or batches can be pushed through faster, maybe through “complete batch” tags or tagged as major session events?

That or there is some sort of back-end ingestion difference based on what generation your account is associated with? I’m truly just brainstorming; none of this documented or recorded anywhere besides what I’m experiencing.

Edit: this behavior continued for hours, leaving 4-5 hours without live HR data in my cloud account. This might suggest that not all sync instances carry information for all sensors, and they most likely back-fill the rest of the shown data in larger batch dumps like mornings. In that case, I would be led to believe that the Gen4 smart sensing enables more continuous payloads than my Gen3 does for daytime readings.

Final Edit: I had a random update to the current HR sensor earlier today and I couldn’t place why at first, but the update came when my heart rate hit 130, so I wonder if the ring triggered an “activity” payload? Maybe the Gen3 only updates heart rate at certain thresholds in daytime payloads.

[louisp (Louis)]

Thank you for the inputs, this definitely seems like the Gen 3 to Gen 4 differences.

I did read somewhere on a Forum over the weekend, someone mentioned that the granularity of the Gen 4 is better.

But there is definitely a difference between the 2 generations in terms of data and syncing.

However, could you perhaps provide some screenshots from what your Dashboards are looking like now? Since it has been over a week since you installed the plugin?

Here is my Dashboard as of right now:

[louisp (Louis)]

Just to add some more information here.

I am working on adding more sensors, like Resilience, SpO2, VO2 Max, Stress etc.:

However, the Oura API documentation is definitely out of date and in some cases, just plain wrong:

Look at the Scope for SpO2:

When I use this spo2Daily scope, I get a 401 Unauthorized error

Then I just randomly tried spo2, then I was finally able to get a value back without an Auth error…

[willis-63]

Absolutely, I haven’t set up a full dashboard for all sensors yet, but I’ve implemented a graph that uses a few of them on my main dash that I love.

Don’t mind the misalignment in the bottom, it renders correctly on my wall tablet, but I built this graph using Apex Charts card. It shows a weeks worth of trends for my sleep and readiness score. I do like your idea of displaying light, deep, and REM sleep durations as bar graphs too, so I may find a way to utilize that if space allows.

[louisp (Louis)]

Oura Ring v2.0.0 Released - Production Ready with Critical Bug Fixes!

I’m excited to announce v2.0.0 of the Oura Ring Custom Integration is now available! This release brings critical bug fixes that make the integration fully functional and production-ready.

Critical Fixes

This release resolves several issues that were preventing the integration from working properly:

Enhanced Error Handling

• Better exception handling for token validation failures
• More informative error messages for troubleshooting
• Improved logging for OAuth session states

New Features

Added 13 New Sensors

Comprehensive Testing

• All 39 automated tests passing
• Docker-based test environment
• Validated against Home Assistant 2025.11

Breaking Changes & Migration

Entity IDs have changed from sensor.oura_* to sensor.oura_ring_*

How to Preserve Your Historical Data

Don’t worry - you won’t lose your data! Follow this simple process:

Option 1: Rename Device to Match Old Naming (Recommended)

1. Upgrade the integration via HACS
2. Go to Settings → Devices & Services → Oura Ring
3. Click on your Oura device
4. Click the (settings) icon in the top right
5. Rename device to: Oura (exactly, no “Ring”)
6. Click the ︙ (3-dot menu) in the top right
7. Select “Rename entities”
8. All 43 entities will be renamed to match the old format (sensor.oura_*)
9. All historical data is preserved!

Option 2: Custom Device Name + Preserve History

1. Follow Option 1 first to get sensor.oura_* entity IDs
2. Then rename your device to anything you want (e.g., “Louis’ Oura”)
3. Use “Rename entities” again
4. Home Assistant automatically preserves history through renames

Important: Do NOT delete and re-add the integration - this will lose your history!

What’s Included

• 43 Sensors across all Oura metrics
• Sleep, Readiness, Activity, Heart Rate, HRV, Stress, Resilience, SpO2, and more
• OAuth2 Authentication with proper token handling
• Historical Data Loading (14 days on first setup, configurable 1-90 days)
• Long-Term Statistics support for all sensors
• Entity Categories for better UI organization
• Multi-Account Support
• HACS Compatible

Full documentation: GitHub Repository

What’s Next

All critical bugs are now fixed and the integration is production-ready. Future updates will focus on:

• Additional metrics as Oura releases new API endpoints
• Enhanced dashboard templates
• Performance optimizations

Acknowledgments

Huge thanks to:

• The Home Assistant community for feedback and testing
• Original component by nitobuendia
• Development assistance: Claude Sonnet 4.5

Full Changelog

See the complete v2.0.0 Release Notes on GitHub.

[louisp (Louis)]

Just released version 2.1.0 - Release v2.1.0 - Low Battery Alert Sensor · louispires/oura-v2-custom-component

A lot more resilient to network issues and a new Flag to see when your battery is low.