Skip to main content

Headspace: Authorizing an empathetic AI companion at consumer scale

Headspace is a global mental-health platform with over 105 million app downloads and 90 million lives reached. Its AI companion, Ebb, has handled more than 6 million conversations since launching, and every message Ebb processes runs through an OpenFGA authorization check.

At a glance​

IndustryMental health / consumer health
Use caseAI companion (Ebb) gating
Scale90M+ lives, 105M+ downloads, 6M+ Ebb messages
DeploymentSelf-hosted
Key features usedBatchCheck, contextual tuples, graph design, Terraform-managed model

Why OpenFGA​

Ebb is gated on a combination of business rules: who the member is contracted through, which country they are messaging from, which language their app is set to, and whether their employer has opted them out. A pure RBAC system could not express this without exploding into a role per combination, and a hand-rolled SQL check ran 10-15 seconds in the worst case — unacceptable for a chat experience.

The Headspace team chose OpenFGA so the AI gating rules could live in a single relationship graph the platform team owned, with the same model evaluated from every service that fronts Ebb.

Architecture​

  • Wrapper API in front of OpenFGA. Application services do not call the OpenFGA store directly. They call an internal authorization service that fans out four parallel BatchCheck requests — assigned-to-Ebb, country-allowed, language-allowed, and not-blocked-by-org — and combines the results.
  • Inverted graph for performance. The original model put the AI feature at the top with users below; a check meant traversing the entire user population. Flipping the direction so the user is the object and Ebb access is reached through unions of small relations dropped end-to-end latency from 10-15 seconds to 10-15 milliseconds.
  • Bidirectional tuple writes. When a member-to-feature relationship is written, the inverse tuple is written at the same time, keeping reads cheap in either direction.
  • Terraform-managed model and static tuples. The authorization model and the static enablement tuples (countries, languages, default org policies) ship through the Headspace OpenFGA Terraform provider, so model changes go through the same review pipeline as infrastructure.
  • Hidden model version. The wrapper API does not expose the OpenFGA model ID to consumers; rolling forward to a new model version is a deploy of the wrapper, not a coordinated change across every caller.
  • SDK 1.10 conflict resolution. The team adopted the conflict-resolution behavior shipped in SDK 1.10 to safely handle concurrent tuple writes during high-traffic enrollment events.

Outcomes​

  • End-to-end Ebb authorization in 10-15 ms, down from 10-15 seconds.
  • Per-user blocking added without touching call sites — a new relation in the model and a tuple write was enough; no service had to ship code.
  • Single source of truth for AI gating rules, owned by the platform team and reviewed in Terraform.
  • Operational headroom to extend Ebb gating (new languages, new contracts, new opt-out criteria) without rewriting application code.

Source​

This case study is based on a presentation in the OpenFGA community meeting by Jeremy, principal engineer at Headspace. Supporting public material on Ebb is available at headspace.com.