Thrive AI Health

Authentication

Two credential types, a server-side tenant API key and short-lived member bearer tokens, plus an HMAC secret for verifying outbound events. Never both headers on the same request.

Auth flow

Member access tokens

  • Access tokens issued by POST /v1/auth/token are short-lived bearer tokens.
  • TTL: 3600 seconds (1 hour).
  • Member tokens are signed JWTs. The scope claim is part of the public contract and may be parsed by partners to drive authorization state. All other claims are internal; their names, types, and presence may change without notice.
  • Anticipatory renewal (recommended): from your backend, mint a fresh token when the client-held token has less than ~60 seconds of lifetime remaining. This avoids the 401 retry spike under load.
  • Reactive renewal (fallback): on any 401 unauthorized, call POST /v1/auth/token again from your backend and retry the original request once with the new token.

Tenant API keys

Initial provisioning

The initial tenant API key is handed off by Thrive AI Health during partner onboarding, after the partner agreement is signed. Sandbox credentials are issued at the start of integration so the partner can build against the sandbox environment; production credentials are issued separately at go-live. In both environments, delivery is a one-time secure share; the key is never retrievable through the API. If the initial key is lost before you can rotate it, contact your Thrive AI Health onboarding representative for a reissue, which voids the lost key.

The event-signing HMAC secret is provisioned in the same handoff, but unlike the tenant key it can be self-recovered via POST /v1/auth/signing-secret/rotate (authenticated by the tenant key).

Storage and handling

  • The tenant API key is a server-side credential and must never be embedded in mobile apps or browser clients.
  • Store the key in a backend secret manager and inject it only into trusted backend services.

Rotation guidance

  • Rotate immediately upon suspected compromise.
  • Rotate at least every 90 days.
  • Use the dual-key grace window exposed by POST /v1/auth/tenant-key/rotate so the new key can be deployed to every service before the old one is revoked.

Event-signing HMAC secret

Initial provisioning

The initial signing secret is handed off alongside the tenant API key at the end of partner onboarding. After the initial handoff, partners rotate the secret themselves with POST /v1/auth/signing-secret/rotate: no need to contact your onboarding representative for routine rotations.

Storage and handling

  • The signing secret is a symmetric key held by both Thrive AI Health (to sign outgoing events) and the partner (to verify them). Protect it with the same posture as the tenant API key: backend-only, secret manager, never embedded in mobile or browser clients.
  • A partner who operates multiple event verifiers (multi-region, blue/green, CI) must deploy every rotation to all of them before the grace period expires.

Rotation guidance

  • Rotate immediately upon suspected compromise.
  • Rotate at least every 90 days.
  • Use the grace window exposed by POST /v1/auth/signing-secret/rotate so every verifier can switch before the old secret is revoked.

Setup (once)

Partner backend stores the tenant API key and the event-signing HMAC secret in a backend secret manager.

User provisioning (once per user)

For a new partner-side user, the partner backend calls POST /v1/users with the tenant API key. The returned canonical user_id is reused for every subsequent call on that user.

Mint

Partner backend calls POST /v1/auth/token with the tenant API key and the user_id to get a short-lived member bearer token.

Use

Partner backend forwards the access_token to the client. The client calls /v1/users/{user_id}/* endpoints with authorization: Bearer <access_token>.

Renew

Before the token expires (see Anticipatory renewal above), or on any 401 unauthorized, the client asks the partner backend for a new token. The partner backend repeats step 3 and forwards the new access_token down.

Full request/response schemas for every auth endpoint live in the Interactive reference.

Introduction

The Thrive AI Health Partner APIs connect partner applications to Thrive AI Health's platform; wearable integrations, personalized coaching, activity and sleep tracking, lab analysis, and AI-generated health insights.

Base URL and format

Environments, authentication headers, JSON conventions, pagination, dates, and other wire-level details that apply to every endpoint.

On this page

Auth flowMember access tokensTenant API keysInitial provisioningStorage and handlingRotation guidanceEvent-signing HMAC secretInitial provisioningStorage and handlingRotation guidanceRecommended member-token flowSetup (once)User provisioning (once per user)MintUseRenew