Tenancy & workspaces
OpenHI is multi-tenant. Almost every request runs in the context of a tenant and often a workspace inside that tenant.
Core ideas
Section titled “Core ideas”| Concept | Meaning |
|---|---|
| Tenant | Top-level organization or customer boundary |
| Workspace | Sub-unit inside a tenant (clinic, team, property, brand, and so on) |
| Membership | Links a user to a tenant (and optionally a workspace) |
| Roles | What a user can administer on the platform vs what they do in an organization |
Resource URLs do not embed tenant or workspace in the path. Scope comes from the authenticated session (JWT claims resolved server-side). Switching tenant or workspace means obtaining a session scoped to the new context, not rewriting every URL.
Roles at a glance
Section titled “Roles at a glance”Two related surfaces matter in apps:
- Platform roles: administrative authority on OpenHI itself (for example admin vs member at tenant or workspace scope).
- Organization roles: job function inside a workspace (scheduling, intake, billing, clinical work, and similar).
Clients should treat the claims on the current token as the source of truth for what the signed-in user can do right now. Use management APIs when administering other people.
Practical takeaway
Section titled “Practical takeaway”Design clients around session scope plus resource APIs, not around inventing per-tenant base paths. See API conventions for how that shows up on the wire.