Glossary
Quick reference for terms used throughout the Connect with Loop documentation.
OAuth / OIDC terms
| Term | Definition |
|---|---|
| Access token | An opaque credential (prefixed lph_at_) that authorizes a single API call on behalf of a user. Short-lived (default 1 hour). Sent as Authorization: Bearer <token>. |
| Authorization code | A short-lived, single-use code returned by /v1/oauth/authorize after the user grants consent. Exchanged for tokens at /v1/oauth/token. Expires after 60 seconds. |
| Authorization server | The Loop identity service (identity.platform.loop.health) that issues tokens and manages grants. |
| Client ID | A public identifier for your registered OAuth application. Safe to embed in client-side code. |
| Client secret | A confidential credential for server-side (confidential) apps. Never embed in mobile or browser code. |
| Code challenge | BASE64URL(SHA256(code_verifier)) — sent with the authorization request. The server uses it to verify the code verifier during token exchange. |
| Code verifier | A random string (43–128 characters) generated by the client for PKCE. Stored in the session, sent during token exchange. |
| Confidential client | An app that can securely store a client_secret (server-side web apps). Uses both PKCE and the secret. |
| Consent screen | The Loop-hosted UI that shows users which scopes your app is requesting and lets them Allow or Deny. |
| Grant | A record of a user’s consent for a specific app to access specific scopes. Stored in oauth_grants. Revocable. |
| ID token | A short-lived JWT (5 minutes) returned alongside the access token when openid scope is requested. Proves who the user is. |
| Introspection | POST /v1/oauth/introspect — how Loop services validate an access token’s authenticity and scope. |
| OIDC (OpenID Connect) | An identity layer on top of OAuth 2.0 that provides user identity via ID tokens. |
| PKCE (Proof Key for Code Exchange) | RFC 7636. A mechanism to bind the authorization request to the token exchange, preventing code interception attacks. Required for all Loop clients. |
| Public client | An app that cannot securely store a secret (mobile apps, SPAs, CLIs). Relies on PKCE alone for security. |
| Redirect URI | The URL Loop redirects the user to after authorization. Must exactly match a registered URI. |
| Refresh token | An opaque credential (prefixed lph_rt_) used to obtain a new access token without re-prompting the user. Rotated on every use. |
| Resource server | Any Loop platform service (clinical, payments, etc.) that accepts access tokens and enforces scopes. |
| Revocation | The act of invalidating a token or grant. Users revoke via Connected Apps; apps revoke via POST /v1/oauth/revoke. |
| Scope | A permission string (read:biomarkers, write:protocols, etc.) that limits what an access token can do. |
| State | A random CSRF-prevention token sent with the authorization request and validated in the callback. |
Loop-specific terms
| Term | Definition |
|---|---|
| BAA (Business Associate Agreement) | A HIPAA-required contract between Loop and apps that handle PHI. Required before PHI-scoped tokens are issued. |
| Brand | A Loop brand context (loop, loopbio, etc.) embedded in the ID token’s brand claim. Determines which services and data are accessible. |
| Connect with Loop | The official name for the OAuth integration surface. Always capitalized, never “Sign in with Loop”. |
| Connected Apps | The user-facing page where Loop users see all OAuth grants and can revoke them. |
| Developer portal | developers.platform.loop.health — where you register apps, configure redirect URIs, and manage secrets. |
| M2M (Machine-to-Machine) | The client_credentials grant used for service-to-service calls within the platform. No user context. See migration-from-m2m. |
| PHI (Protected Health Information) | Health data protected under HIPAA. Scopes returning PHI require a BAA. The consent screen uses stronger language for PHI scopes. |
| Safe-view | The platform convention for returning PHI in a format that minimizes exposure (per ADR-0046). |
| Scope bundle | A convenience alias that expands to multiple scopes (e.g., loop.health.basic → openid profile email read:account). |
| Signing secret | A per-app secret used to HMAC-sign webhook deliveries. Separate from the client secret. |
Token prefixes
| Prefix | Meaning |
|---|---|
lph_at_ | Access token |
lph_rt_ | Refresh token |