Oura integration
How BetterBite uses Oura data, and why it asks for each scope.
BetterBite is an AI calorie and nutrition tracker for iPhone. You photograph a meal and it logs the calories, protein, carbohydrates and fat. The Oura integration exists for one purpose: to make a person's daily calorie budget reflect the day they actually had, rather than an activity level they picked once during onboarding.
Scopes requested, and what each is for
| Scope | Used for |
|---|---|
daily | Daily sleep, readiness and activity summaries. The activity document's total calories is the figure the calorie budget is calculated from; the readiness and sleep scores are shown on the home ring. |
personal | The Oura user identifier only, so webhook events can be matched back to the right account. No name or email is stored. |
Endpoints called
Four, at most once every ten minutes per user, plus one at connection.
GET /v2/usercollection/daily_sleepGET /v2/usercollection/daily_readinessGET /v2/usercollection/daily_activityGET /v2/usercollection/sleepGET /v2/usercollection/personal_info— once, at connection
Webhooks
BetterBite subscribes through POST /v2/webhook/subscription for
daily_sleep, daily_readiness, daily_activity and
sleep, on create, update and delete. The endpoint answers the verification challenge
with a token held server-side, and verifies every event's
x-oura-signature as an uppercase hex HMAC-SHA256 of the timestamp and body.
An event invalidates that user's cached readings rather than triggering an immediate re-fetch, so a sync burst cannot become a burst of API calls. Subscriptions are renewed automatically before they expire.
How the data is used
BetterBite's calorie target is built on an estimated total daily energy expenditure — body metrics multiplied by an activity level the user chose during onboarding. Oura measures that same quantity every day, so where a measurement exists the app stops budgeting against a guess.
Only the expenditure above what the target already assumes is credited, and only a fraction of that. Adding back 100% of an estimated burn would pay twice for the activity already built into the target.
Oura's daily activity document covers a calendar day, and is treated as one.
- A quiet day never lowers a calorie target.
- Adjustments are capped, thresholded and rounded, so the number stays stable through the day.
- Readings that are stale or implausible against expectation are refused rather than used.
- An Oura day total and an Apple Health workout are never summed — the same session would otherwise be counted twice.
- Oura has no strain metric, so its 0–100 activity score is never displayed under a label borrowed from another device.
- The user can set how much of an active day is credited, or switch the behaviour off.
Handling and security
- The client secret, all tokens and every call to
api.ouraring.comlive in a Cloudflare Worker. No secret ships inside the iOS binary. - Authorisation runs in
ASWebAuthenticationSession. The OAuth state is stored server-side, is single-use, and is bound to the account, so a callback cannot attach one person's Oura account to another's. - Responses are cached for ten minutes per user; a 429 is surfaced and served from cache, never retried into.
- The integration is read-only. Nothing is ever written back to Oura.
- Disconnecting deletes our copy of the tokens and the user identifier immediately. Deleting a BetterBite account does the same.
Contact
Questions about this integration: trybiteai.com/support.