ConnectOverview

Connect with Loop

Connect with Loop is the OAuth 2.0 + OpenID Connect access layer for every application — first-party or third-party — that consumes the Loop Platform. This document is the canonical product definition. If implementation diverges from what’s here, the implementation is wrong.

What this is

A single, scoped, user-consented way to call the Loop Platform on behalf of a user.

  • First-party apps (my-loop-health, apps/admin, the iOS/Android apps when they exist) use the same flow that third parties use. Loop eats its own dog food.
  • Third-party apps (partner gyms, clinical portals, data analysis tools, a hypothetical Apple Health bridge, a research lab’s intake tool) register against the platform, get a client_id + client_secret, and obtain user consent before reading or writing any data.
  • Machine-to-machine integrations (jobs, cron, internal service-to-service) continue to use the existing client_credentials flow on services/identity and are out of scope for this document.

Why this exists

Today, my-loop-health hits the database directly and inherits whatever permissions the server has. That’s fast to build, but:

  • Users can’t see, audit, or revoke what an app can do with their data.
  • A new third party requires bespoke integration code per partner.
  • HIPAA scrutiny is harder to defend: who accessed what, when, with whose consent?
  • The same auth pattern can’t extend to mobile, browser extensions, partner dashboards.

Connect with Loop solves all four with one primitive: a scoped, user-consented, revocable token.

What you can do with it

If you are a developer building against the Loop Platform — whether you work at Loop or for a partner — Connect lets you:

  1. Add “Connect with Loop” to your app. Users click a button, see a consent screen listing the data your app wants, click Allow, and your app gets a token.
  2. Read user data with that token. Biomarkers, protocols, memberships, communications, follows — whatever scopes the user granted.
  3. Write on the user’s behalf. Start a protocol, mark a check-in, post to community — again, only the scopes the user explicitly granted.
  4. Listen to events. Subscribe webhooks to events the user authorized (new biomarker result, protocol started, etc.).
  5. Refresh access without re-prompting. Long-lived refresh tokens keep your app working until the user revokes.
  6. Be revoked cleanly. Users see a Connected Apps list in their account, click Revoke, and your token stops working immediately.

What you cannot do with it

  • Read data the user did not consent to.
  • Bypass scope checks by inferring identity from anything other than the access token.
  • Cache user data beyond what’s specified in the data-retention scope you requested.
  • Subscribe to events outside your granted scopes.

These are enforced at the service boundary. Every SDK call passes the access token; every service validates scopes before responding.

Reading this documentation

Read in this order:

  1. Quickstart — register an app, get tokens, make your first call. ~5 minutes.
  2. Authorization flow — the OAuth 2.0 authorization_code + PKCE flow in detail.
  3. Scopes — every scope the platform exposes, what data it gates, which service owns it.
  4. Tokens — access tokens, refresh tokens, expiry, rotation, format.
  5. Webhooks — receive events from the platform after the user grants you the relevant scopes.
  6. Security model — PKCE requirements, redirect URI rules, CORS, HIPAA implications.
  7. Errors — every error code the OAuth endpoints can return.
  8. Branding — the “Connect with Loop” button kit and usage guidelines.
  9. Glossary — key terms used throughout this documentation.
  10. Migrating from M2M — how to move from client_credentials to user-scoped tokens.

The promise

This document is the contract. Three commitments:

  • No undocumented endpoints. If it’s not described here or in a per-service OpenAPI spec, it doesn’t exist for third parties.
  • No silent breakages. OAuth endpoints are versioned (/v1/oauth/*). Breaking changes ship /v2/* paths and a deprecation timeline.
  • One flow, all apps. First-party and third-party apps use the same authorization_code + PKCE path. If Loop ever adds an unsafer shortcut for itself, that’s a bug.
Quickstart