vellum-ai/vellum-assistant

Oura Ring Integration

Verbinden Sie den Oura Ring des Benutzers, um Schlaf-, Herzfrequenz-, Bereitschafts-, Aktivitäts- und andere Gesundheitsdaten über die Oura Cloud API V2 abzurufen.

Voraussetzungen

• Ein Oura Ring (Gen 3 oder Ring 4) mit einer aktiven Oura-Mitgliedschaft (6 $/Monat für API-Zugriff erforderlich)
• Die Oura App muss installiert und mit dem Ring gekoppelt sein
• Ein Oura Cloud-Konto unter https://cloud.ouraring.com

Einrichtung

1. Entwickleranwendung registrieren

Lassen Sie den Benutzer unter https://developer.ouraring.com/applications eine neue Anwendung erstellen:

• Anzeigename: Der gewünschte Name des Benutzers für die Integration
• Beschreibung: Kurze Beschreibung der Integration
• Kontakt-E-Mail: E-Mail des Benutzers
• Website: Eine beliebige gültige URL (z. B. eine persönliche Website)
• Datenschutzrichtlinie / Nutzungsbedingungen: Beliebige gültige URLs (Pflichtfelder, werden aber bei persönlichen Apps nicht geprüft)
• Weiterleitungs-URIs: http://localhost:3000/callback
• Bereiche: Alle benötigten Bereiche aktivieren. Empfohlen: personal, daily, heartrate, sleep, workout, spo2, stress, heart_health, session, ring_configuration

Speichern Sie die Client-ID und das Client-Secret.

2. OAuth-Flow ausführen

Speichern Sie das Client-Secret sicher mit assistant credentials prompt, schreiben Sie dann das OAuth-Hilfsskript auf dem Rechner des Benutzers und führen Sie es aus:

#!/usr/bin/env python3
"""Oura Ring OAuth2-Helfer – fängt Auth-Code und tauscht ihn sofort gegen Token ein."""
from http.server import HTTPServer, BaseHTTPRequestHandler
from urllib.parse import urlparse, parse_qs, urlencode
import urllib.request, json, webbrowser, ssl

CLIENT_ID = 'YOUR_CLIENT_ID'
CLIENT_SECRET = 'YOUR_CLIENT_SECRET'
REDIRECT_URI = 'http://localhost:3000/callback'
SCOPES = 'email personal daily heartrate workout tag session spo2 ring_configuration stress heart_health'

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        parsed = urlparse(self.path)
        if parsed.path == '/':
            params = urlencode({
                'response_type': 'code', 'client_id': CLIENT_ID,
                'redirect_uri': REDIRECT_URI, 'scope': SCOPES, 'state': 'assistant'
            })
            self.send_response(302)
            self.send_header('Location', f'https://cloud.ouraring.com/oauth/authorize?{params}')
            self.end_headers()
        elif parsed.path == '/callback':
            code = parse_qs(parsed.query).get('code', [''])[0]
            if code:
                token_data = urlencode({
                    'grant_type': 'authorization_code', 'code': code,
                    'redirect_uri': REDIRECT_URI, 'client_id': CLIENT_ID,
                    'client_secret': CLIENT_SECRET,
                }).encode()
                try:
                    req = urllib.request.Request('https://api.ouraring.com/oauth/token',
                        data=token_data,
                        headers={'Content-Type': 'application/x-www-form-urlencoded'},
                        method='POST')
                    resp = urllib.request.urlopen(req, context=ssl.create_default_context())
                    result = json.loads(resp.read())
                    with open('/tmp/oura_tokens.json', 'w') as f:
                        json.dump(result, f, indent=2)
                    self.send_response(200)
                    self.send_header('Content-Type', 'text/html')
                    self.end_headers()
                    self.wfile.write(b'<html><body><h1>Verbunden! Sie können diesen Tab schließen.</h1></body></html>')
                    print(f'\nToken gespeichert unter /tmp/oura_tokens.json')
                except Exception as e:
                    self.send_response(500)
                    self.end_headers()
                    self.wfile.write(f'Token-Austausch fehlgeschlagen: {e}'.encode())
    def log_message(self, *a): pass

print('Browser für Oura-Autorisierung wird geöffnet...')
webbrowser.open('http://localhost:3000')
HTTPServer(('localhost', 3000), Handler).serve_forever()

Ausführen mit python3 /pfad/zum/skript.py auf dem Rechner des Benutzers (host_bash). Der Benutzer autorisiert im Browser, das Skript fängt den Code ab und tauscht ihn in unter einer Sekunde gegen Token ein.

Wichtig: Auth-Codes laufen nach ca. 30 Sekunden ab. Lassen Sie den Benutzer KEINE Codes manuell einfügen – verwenden Sie dieses Skript, um sie automatisch abzufangen und auszutauschen.

3. Token speichern

Nach dem OAuth-Flow die Token aus /tmp/oura_tokens.json auslesen und speichern:

• access_token – im Credential Vault mit Einfügevorlage für den Authorization-Header (Bearer-Präfix) von api.ouraring.com und allowed_tools: ["bash"] speichern
• refresh_token – im Credential Vault für die Token-Aktualisierung speichern
• Token laufen nach ca. 30 Tagen ab. Erinnerung zur Aktualisierung vor Ablauf setzen.

4. Verbindung überprüfen

Test mit dem persönlichen Informations-Endpunkt:

curl -s -H "Authorization: Bearer $TOKEN" "https://api.ouraring.com/v2/usercollection/personal_info"

Verfügbare Endpunkte

Alle Endpunkte verwenden GET https://api.ouraring.com/v2/usercollection/{type} mit den Abfrageparametern start_date und end_date (Format JJJJ-MM-TT).

Endpunkt	Daten	Hinweise
/v2/usercollection/daily_sleep	Schlaf-Score, Dauer, Effizienz, Schlafphasen	Am besten nach der typischen Aufwachzeit prüfen
/v2/usercollection/sleep	Detaillierte Schlafperioden mit HF, HRV, Bewegung	Rohdaten der Schlafperioden
/v2/usercollection/daily_readiness	Bereitschafts-Score, HRV-Gleichgewicht, Erholung	Morgendliche Check-in-Kennzahl
/v2/usercollection/daily_activity	Schritte, Kalorien, Bewegung, Inaktivität	Aktivitätsübersicht
/v2/usercollection/heartrate	Kontinuierliche HF (verwenden Sie start_datetime/end_datetime im ISO-Format)	Kann groß sein – Datumsbereich einschränken
/v2/usercollection/daily_spo2	Blutsauerstoffwerte	Nächtlicher Durchschnitt
/v2/usercollection/daily_stress	Stress-Score und Erholung	Tägliche Stressverfolgung
/v2/usercollection/workout	Erkannte Workouts mit HF, Kalorien	Automatisch erkannt oder manuell
/v2/usercollection/personal_info	Alter, Gewicht, Größe, E-Mail	Guter Verbindungstest

Token-Aktualisierung

Token laufen nach 30 Tagen ab. Mit folgendem Befehl aktualisieren:

curl -s -X POST "https://api.ouraring.com/oauth/token" \
  -d "grant_type=refresh_token&refresh_token=$REFRESH_TOKEN&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET"

Den neuen access_token und refresh_token aus der Antwort speichern.

Tipps

• Neue Ringe benötigen 1–2 Nächte zur Kalibrierung, bevor die Daten aussagekräftig sind
• Schlafdaten erscheinen in der Regel einige Stunden nach dem Aufwachen des Benutzers
• Herzfrequenzdaten während des Trainings erscheinen, nachdem das Training über die Oura App synchronisiert wurde
• Ratenlimit: 5000 Anfragen pro 5 Minuten
• Ring 4 und Gen 3 Benutzer MÜSSEN eine aktive Oura-Mitgliedschaft für den API-Zugriff haben