Roles and Permissions

Zus uses role-based access control (RBAC) to manage what users and App Clients can do. Every user and App Client is assigned exactly one role at creation time, and that role determines which Zus services and endpoints they can access and which operations (read, create, update, delete) they can perform.

Zus provides four built-in roles. Custom roles are not currently supported.

Choosing a role

Use this table to pick the right role. Details for each role follow below.

Role	Assign to	Can manage users & App Clients?	Can access patient data?	Can get tokens for other users?
Builder Admin	Engineers, admins, M2M App Clients that manage your Builder account	✅	✅ Full read/write on all allowed FHIR resources	❌
Builder Data Integration	App Clients that sign users in on their behalf (EHR integrations, Zus apps embedded in your UI)	✅	✅ Full read/write on all allowed FHIR resources	✅
Care Team User	Clinicians and operational users who work with patients but shouldn't change account settings	❌	✅ Read all allowed resources; write a limited set	❌
Permissionless	Users you need to revoke access for (with important caveat)	❌	❌	❌

Builder Admin

Full administrative access within a Builder account. Assign this role to engineers, account administrators, and most machine-to-machine App Clients.

A Builder Admin can:

Manage FHIR data — read, create, update, and delete all FHIR resource types, except for certain Conformance, Terminology, and Security resource types that Zus manages on your behalf.
Manage identities — read, create, update, and delete users and App Clients within the Builder account.
Access partner Builders — if your Builder has Cross-Builder Grants in place, Builder Admins can also read data from those partner Builders.

Builder Data Integration

Full administrative access within a Builder account, plus the ability to get access tokens on behalf of users. Assign this role to App Clients that sign users in on their behalf, such as EHR integrations or Zus apps embedded in your own UI. Do not assign it to people.

Builder Data Integration can do everything Builder Admin can, plus:

Get tokens for users: call the proxy-token endpoint (POST /auth/users/proxy-token) to get an access token for a user in your Builder account.

Assign to App Clients only
This role lets the holder act as any user in your organization. To keep that access limited to systems you control, assign it only to App Clients and never to individual users.

Care Team User

Patient-data access without administrative power. Assign this role to clinicians, care coordinators, and other operational users who need to work with patient records but shouldn't be able to change account configuration or manage other users.

A Care Team User can:

Read all FHIR resource types (with the same Conformance / Terminology / Security exceptions as Builder Admin).
Create, update, and delete a limited set of clinical resource types — currently Patient, CarePlan, CareTeam, and Goal.

A Care Team User cannot:

Create, update, or delete users or App Clients.
Modify Builder account configuration.

Permissionless

No access to Zus UIs or APIs. Assign this role to users for whom you want to revoke access. Alternatively, you can simply delete the user to fully revoke access.

⚠️
Permissionless does not revoke Snowflake access
If your organization uses a Zus-hosted Snowflake reader account, changing a user's role to Permissionless does not remove their Snowflake access. To remove Snowflake access, you must instead delete the user from the Users page.

What's not covered by roles

Roles control access within a single Builder account. They do not govern:

Cross-Builder access — handled separately via Cross-Builder Grants.
Snowflake access — managed by Zus support, as noted above.
SSO and password policies — configured at the Builder level, independent of role assignment.