Communitygithub.com

vellum-ai/vellum-assistant

OAuth2를 통해 Oura Ring 연결 — 앱 등록, 토큰 교환 및 자격 증명 저장

vellum-assistant란 무엇인가요?

이 스킬은 개발자 또는 AI 에이전트가 사용자의 Oura Ring을 Oura Cloud API V2에 연결할 수 있도록 지원합니다. Oura Ring Gen 3 또는 Ring 4 소유자와 활성 Oura 멤버십($6/월)이 필요합니다. 주요 단계로는 Oura 개발자 포털에서 애플리케이션 등록, OAuth2 인증 코드를 자동으로 캡처 및 교환하는 Python 스크립트 실행, 획득한 액세스 및 리프레시 토큰을 자격 증명 볼트에 안전하게 저장하는 과정이 포함됩니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 플랫폼에서 사용할 수 있으며, 수동 복사 없이 브라우저 기반 OAuth 흐름을 처리하고 수면, 심박수, 활동, 산소 포화도 등 다양한 건강 데이터 엔드포인트를 제공합니다. 토큰 만료(30일) 처리를 위한 리프레시 메커니즘과 연결 확인을 위한 테스트 명령도 포함되어 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vellum-ai/vellum-assistant/tree/HEAD/skills/oura-setup

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Oura Ring 통합

사용자의 Oura Ring을 연결하여 Oura Cloud API V2를 통해 수면, 심박수, 준비 상태, 활동 및 기타 건강 데이터를 가져옵니다.

전제 조건

  • 활성 Oura 멤버십($6/월, API 액세스 필수)이 있는 Oura Ring(Gen 3 또는 Ring 4)
  • Oura 앱이 설치되어 있고 링과 페어링됨
  • https://cloud.ouraring.com 의 Oura Cloud 계정

설정

1. 개발자 애플리케이션 등록

사용자에게 https://developer.ouraring.com/applications 로 이동하여 새 애플리케이션을 만들도록 안내합니다:

  • 표시 이름: 사용자가 원하는 통합 이름
  • 설명: 통합에 대한 간략한 설명
  • 연락처 이메일: 사용자의 이메일
  • 웹사이트: 유효한 URL (예: 개인 웹사이트)
  • 개인정보 처리방침 / 서비스 약관: 유효한 URL (필수 필드, 개인 앱에는 강제되지 않음)
  • 리디렉션 URI: http://localhost:3000/callback
  • 범위: 필요한 모든 범위를 활성화합니다. 권장: personal, daily, heartrate, sleep, workout, spo2, stress, heart_health, session, ring_configuration

클라이언트 ID와 클라이언트 시크릿을 저장합니다.

2. OAuth 흐름 실행

assistant credentials prompt를 사용하여 클라이언트 시크릿을 안전하게 저장한 후, 사용자 컴퓨터에서 OAuth 도우미 스크립트를 작성하고 실행합니다:

#!/usr/bin/env python3
"""Oura Ring OAuth2 도우미 — 인증 코드를 캡처하고 즉시 토큰으로 교환합니다."""
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>연결되었습니다! 이 탭을 닫아도 됩니다.</h1></body></html>')
                    print(f'\n토큰이 /tmp/oura_tokens.json에 저장되었습니다.')
                except Exception as e:
                    self.send_response(500)
                    self.end_headers()
                    self.wfile.write(f'토큰 교환 실패: {e}'.encode())
    def log_message(self, *a): pass

print('Oura 인증을 위해 브라우저를 엽니다...')
webbrowser.open('http://localhost:3000')
HTTPServer(('localhost', 3000), Handler).serve_forever()

사용자 컴퓨터에서 python3 /path/to/script.py로 실행합니다(host_bash). 사용자가 브라우저에서 인증하면 스크립트가 코드를 캡처하여 1초 이내에 토큰으로 교환합니다.

중요: 인증 코드는 약 30초 후에 만료됩니다. 사용자에게 수동으로 코드를 붙여넣도록 하지 말고 — 이 스크립트를 사용하여 자동으로 캡처 및 교환하세요.

3. 토큰 저장

OAuth 흐름 후 /tmp/oura_tokens.json에서 토큰을 읽어 저장합니다:

  • access_token — api.ouraring.com 승인 헤더(Bearer 접두사) 및 allowed_tools: ["bash"]에 대한 주입 템플릿과 함께 자격 증명 볼트에 저장
  • refresh_token — 토큰 갱신을 위해 자격 증명 볼트에 저장
  • 토큰은 약 30일 후 만료됩니다. 만료 전에 갱신하도록 알림을 설정하세요.

4. 연결 확인

개인 정보 엔드포인트로 테스트:

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

사용 가능한 엔드포인트

모든 엔드포인트는 GET https://api.ouraring.com/v2/usercollection/{type}을 사용하며, start_date 및 end_date 쿼리 매개변수(YYYY-MM-DD 형식)를 사용합니다.

엔드포인트데이터참고 사항
/v2/usercollection/daily_sleep수면 점수, 지속 시간, 효율, 단계사용자의 일반적인 기상 시간 이후에 확인하는 것이 가장 좋음
/v2/usercollection/sleep심박수, HRV, 움직임을 포함한 상세 수면 기간원시 수면 기간 데이터
/v2/usercollection/daily_readiness준비 점수, HRV 균형, 회복아침 체크인 지표
/v2/usercollection/daily_activity걸음 수, 칼로리, 움직임, 비활동 시간활동 요약
/v2/usercollection/heartrate연속 심박수 (start_datetime/end_datetime을 ISO 형식으로 사용)데이터가 클 수 있음 — 날짜 범위 제한
/v2/usercollection/daily_spo2혈중 산소 포화도야간 평균
/v2/usercollection/daily_stress스트레스 점수 및 회복주간 스트레스 추적
/v2/usercollection/workout심박수, 칼로리를 포함한 감지된 운동자동 감지 또는 수동 입력
/v2/usercollection/personal_info나이, 체중, 키, 이메일좋은 연결 테스트

토큰 갱신

토큰은 30일 후에 만료됩니다. 다음으로 갱신:

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"

응답에서 새 access_token과 refresh_token을 저장합니다.

팁

  • 새 링은 데이터가 의미 있게 나오기 전에 1-2박 동안 보정이 필요합니다.
  • 수면 데이터는 일반적으로 사용자가 기상한 후 몇 시간 후에 나타납니다.
  • 운동 중 심박수 데이터는 Oura 앱을 통해 운동이 동기화된 후에 나타납니다.
  • 속도 제한: 5분당 5000건의 요청
  • Ring 4 및 Gen 3 사용자는 API 액세스를 위해 반드시 활성 Oura 멤버십이 있어야 합니다.

관련 스킬