Access control and roles

Who can do what in HealthyRides, and how quickly a change to someone's access takes effect.

Roles

Every person holds one or more roles in their organization, and each role is a fixed list of permissions defined in one place in the code (platform/packages/auth/src/roles.ts).

A facility organization's roles are facility admin, scheduler and read-only. A provider organization's roles are provider admin, dispatcher and crew. Each role belongs to exactly one side, so nobody can both bid for a ride and pick the winning bid (platform/packages/auth/src/roles.ts; docs/decisions/0025-platform-admin-through-a-platform-organization.md).

Only roles that need patient details hold the permission to read them. On the facility side that is the facility admin and the scheduler, and on the provider side the dispatcher. Crew and read-only users hold no patient permission (platform/packages/auth/src/roles.ts). The roles are designed to HIPAA's minimum-necessary standard; which roles each person holds is their organization's choice (platform/packages/domain/src/agreements/texts/baa-v2.ts).

HealthyRides staff hold two further roles, platform admin and sales, only through HealthyRides' own organization. Neither reads a patient field (docs/decisions/0025-platform-admin-through-a-platform-organization.md; docs/decisions/0041-sales-is-its-own-platform-role-holding-demo-manage-alone.md).

Every request is checked

Each request to the app is checked against the person's membership as it stands in the database at that moment, not against what was true when they signed in (docs/decisions/0011-membership-status-is-checked-on-every-request.md).

So suspending or removing someone ends their access on every device at their next request, and a change of role applies at the next request too (docs/decisions/0011-membership-status-is-checked-on-every-request.md).

The check runs where the app decides who the caller is for real work, not in a layer a request could go around (docs/decisions/0011-membership-status-is-checked-on-every-request.md).

Unique accounts

Each person signs in with an account of their own; shared logins are not part of the product (docs/prd/healthyrides-mvp-prd.md). The terms of service forbid sharing an account (platform/packages/domain/src/agreements/texts/terms-v2.ts).

Who administers access

A facility admin or a provider admin invites, suspends and changes the roles of their own organization's members (platform/packages/auth/src/roles.ts). A change of role is written to the organization's audit log as a permission decision, naming every role of the person who made it (platform/packages/domain/src/memberships/service.ts).

An admin cannot grant a HealthyRides staff role, cannot give one person roles on both sides, and cannot leave their organization without an active admin (platform/packages/domain/src/memberships/service.ts).