Cross-Builder Grants

Overview

This guide covers how you can use Cross-Builder Grants to access and interact with data on behalf of other Builders on Zus that you have a formal relationship with (e.g., business associate of covered entity). For example, if your customers need access to Zus and you are managing their user accounts and patient data, you can use Cross-Builder Grants to do this for them.

A Cross-Builder Grant is a relationship in Zus between two Builders, in which one Builder (e.g., "Customer Builder" above) has granted access to its data in Zus to another Builder (e.g., "Digital Health Co." above) through a Zus approval process, as described below. The Cross-Builder Grant allows only Digital Health Co. users with the Builder Admin role to create and update users and patient data in the Customer Builder. This means that only a limited subset of Digital Health Co.'s users can access Customer Builder's data.

This Cross-Builder Grant does NOT allow the Customer Builder to access Digital Health Co.'s data or any other customer's data that Digital Health Co. is managing. In other words, the Cross-Builder Grant provides access in one direction. A new Cross-Builder Grant from Digital Health Co. to Customer Builder would be required to allow the Customer Builder to interact with Digital Health Co.'s data.

Setting up Cross-Builder Access

Currently Cross-Builder Grants must be created by Zus. If you would like to have a Cross-Builder Grant established, please reach out to our Support team and provide the following information:

Name of Builder / Organization GRANTING access to its data (e.g., "Customer Builder")
Name of Builder / Organization RECEIVING access to data (e.g., "Digital Health Co.")
Nature of the business relationship between the Builders listed above

Using Cross-Builder Grants

Using Cross-Builder Grants with Auth Service

Creating or Updating User for Customer Builder

To create or update a user in a Customer Builder, using an authenticated user in Digital Health Co's Builder, follow the same steps here and specify the BuilderID of the Builder in which the user belongs in the body of your POST request:

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

{
    "data": {
        "type": "auth/users",
        "attributes": {
            "email": "{{Email}}",
            "name": "{{Username}}",
            "userType": "builder",
            "sendPasswordResetEmail": false #Optional boolean (true by default)
        },
        "relationships": {
            "auth/roles": {
                "data": {
                    "type": "auth/roles",
                    "id": "{{RoleID}}" 
                }
            },
            "auth/builders": {
                "data": {
                    "type": "auth/builders",
                    "id": "{{BuilderID}}" #BuilderID of the Customer Builder
                }
            }
        }
    }
}

Retrieving Users in Auth Service

To see all users across all Builders you have access to, simply perform the same GET request you would normally:

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

To see users in a specific Customer Builder, add the BuilderID as a filter parameter:

GET https://api.sandbox.zusapi.com/auth/users?filter[builderId]={{BuilderID}}

To see Builders you have access to:

GET https://api.sandbox.zusapi.com/auth/builders

Using Cross-Builder Grants with ODS (FHIR API)

Creating or Updating FHIR resource for Customer Builder

To create or update a FHIR resource in a Customer Builder, using an authenticated user in Digital Health Co's Builder, specify the BuilderID in the Zus-Account header in your API call:

POST https://api.sandbox.zusapi.com/fhir/Patient

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 body>}'

Retrieving FHIR resources in ODS

To see all patients across all Builders your user has access to, using an authenticated user in Digital Health Co's Builder, simply perform the same GET request you would normally:

GET https://api.sandbox.zusapi.com/fhir/Patient

To see patients in a specific Customer Builder, specify the BuilderID in the Zus-Account header in your API call as in the patient creation example above.

User Permissions

As mentioned above, only users with the Builder Admin role can access another Builder's data using a Cross-Builder Grant. The user will have the same permissions in the Customer Builder as in their own Builder. In other words, a Builder Admin user in Digital Health Co. will have all the permissions of the Builder Admin role when interacting with Customer Builder's data.