Cross-Builder Grants

A Cross-Builder Grant lets one Builder manage users and patient data in another Builder on Zus when the two have a formal business relationship, such as a business associate working for a covered entity. A typical case: you manage Zus accounts and patient data on behalf of your customers.

In the examples on this page, Customer Builder grants access to its data and Digital Health Co. receives it.

How grants work

• One direction only. The grant lets Digital Health Co. work with Customer Builder's data, not the reverse. Customer Builder can't access Digital Health Co.'s data, or the data of any other customer Digital Health Co. manages. Access the other way requires a separate grant.
• Builder Admins only. Only Digital Health Co. users with the Builder Admin role can use the grant, so only a limited subset of its users can access Customer Builder's data. They have the same Builder Admin permissions in Customer Builder as in their own Builder.
• Includes Restricted data. Digital Health Co.'s Builder Admins can also see Customer Builder's resources labeled Restricted, which other Builders can't see. See Specially Regulated Data.

Requesting a grant

Zus creates Cross-Builder Grants. To request one, contact Support with:

1. The Builder granting access (for example, Customer Builder)
2. The Builder receiving access (for example, Digital Health Co.)
3. The business relationship between the two Builders

Managing users in another Builder

To create or update a user in Customer Builder, authenticate as a Builder Admin in Digital Health Co. and follow the steps in Creating Users. In the request body, add an auth/builders relationship with Customer Builder's ID:

POST https://api.sandbox.zusapi.com/auth/users

{
  "data": {
    "type": "auth/users",
    "attributes": {
      "email": "{{Email}}",
      "name": "{USERNAME}",
      "userType": "builder",
      "sendPasswordResetEmail": false
    },
    "relationships": {
      "auth/roles": {
        "data": {
          "type": "auth/roles",
          "id": "{{RoleID}}"
        }
      },
      "auth/builders": {
        "data": {
          "type": "auth/builders",
          "id": "{{BuilderID}}"
        }
      }
    }
  }
}

• auth/builders.data.id is the BuilderID of Customer Builder.
• sendPasswordResetEmail is optional and defaults to true.

To look up users and Builders:

All requests use the base URL https://api.sandbox.zusapi.com.

Managing FHIR data in another Builder

To create, update, or read FHIR resources in Customer Builder, authenticate as a Builder Admin in Digital Health Co. and add a Zus-Account header with Customer Builder's ID:

curl --request POST \
  --url https://api.sandbox.zusapi.com/fhir/Patient \
  --header 'Accept: */*' \
  --header 'Zus-Account: <BuilderID>' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{<FHIR Patient resource>}'

Without the header, a read such as GET /fhir/Patient returns resources from every Builder you can access.

Related pages

• Roles and Permissions
• Creating Users
• FHIR API