Setting up Users

As a Builder Admin, you can use Zus Auth Service APIs to manage two types of accounts within your Builder Org on Zus: users and app clients.

A "user" on Zus is a human who has a name, email address, and credentials to verify their identity as an individual. Users can access Zus APIs and UIs with their credentials.

If you have clinical users, you'll want to add them to a care team and link them with their patients. You may also need them to assume a clinical role within that care team. For this reason, Zus allows you to optionally create a FHIR Practitioner resource for your users and link the FHIR resource to their identity. You can then associate that FHIR Practitioner resource with FHIR Care Teams and Practitioner roles.

If you have patient users that require access to Zus, you'll want to create FHIR patient resources and link them to their user identities.

Setting up a New User in your Organization

Follow the steps below in sequence to set up a new user. NOTE: The easiest way to do this in practice is with the User Creation Guide in our Zus Health Postman Collection, which automates these steps and allows you to create multiple users with one click.

Step 1: Create a Practitioner Resource (Optional)

This can be a minimal resource that just contains your user's first and last names. This call will return a practitioner_id that you should retain. Once created, this Practitioner is available for PractitionerRole assignment and CareTeam linking.

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

{
    "resourceType": "Practitioner",
    "active": true,
    "name": [
                {
                    "family": "{{FamilyName}}",
                    "given": [
                        "{{GivenName}}"
                        ]
                }
            ]
}

Step 2: Create a User in the Auth Service

Step 2a: Specify the role you want the user to have. Your current role options are Builder Admin and Care Team User. Set the RoleName variable's current value to either Builder Admin or Care Team User.

GET https://api.sandbox.zusapi.com/auth/roles?filter[name]={{RoleName}}

{
    "data": [
        {
            "type": "auth/roles",
            "id": "<UUID>", #RoleID used in step 2b
            "attributes": {
                "createdAt": 1638828368,
                "description": "",
                "isManaged": true,
                "name": "Care Team User",
                "permissions": [
                    ....
                ],
                "updatedAt": 1655996421
            }
        }
    ],
    "links": {
        "next": "https://api.sandbox.zusapi.com/auth/roles?filter[name]=Care%20Team%20User&page[count]=50&page[offset]=50",
        "self": "https://api.sandbox.zusapi.com/auth/roles?filter[name]=Care%20Team%20User&page[count]=50&page[offset]=0"
    }
}

Step 2b: Create a user with the role from step 2a. To ensure the user can eventually log in with single sign-on (SSO) if you establish an SSO connection with Zus, the user email with their identity provider must match the email used when creating the user's Zus account below.

Optional fields:

  • Set clientId to the value in the body below so that users are redirected to this documentation website upon resetting their passwords.
  • Set sendPasswordResetEmail to false so that the user does NOT receive an email to reset their password. This istrue by default.

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

{
    "data": {
        "type": "auth/users",
        "attributes": {
            "email": "{{Email}}",
            "name": "{{Username}}",
            "userType": "builder",
            "clientId": "PuzaR6b4U1l2wMC3qciU1qUJI2fOxJLw", #Optional, redirects user to Zus documentation upon resetting their password
            "sendPasswordResetEmail": true, #Optional boolean (true by default)
        },
        "relationships": {
            "auth/roles": {
                "data": {
                    "type": "auth/roles",
                    "id": "{{RoleID}}" #from step 2a
                }
            },
            "fhir/practitioner": {
                "data": {
                    "type": "fhir/practitioner", 
                    "id": "{{OptionalPractitionerID}}" #from step 1
                }
            }
        }
    }
}

Setting up and Managing Patient Users

Overview

If you have patient users that need to access Zus, you can use the Patient Upsert API endpoint to create & update patient users, create & update FHIR patient resources, and link the two together. The Patient Upsert endpoint performs upsert operations on a FHIR patient resource and the patient user linked to that patient resource in the same API call, allowing them to stay in sync as you make updates over time.

This endpoint is intended for the following use cases:

  • Initial simultaneous creation of BOTH new FHIR patient resources and patient users in Auth Service
  • Simultaneous PUT updates to BOTH FHIR patient resources and patient users and ensuring FHIR patient resources and patient users stay in sync (e.g., updating email on the FHIR patient resource and on the patient user)

To make changes to only the patient resource or only the patient user in Auth Service, use the appropriate PUT or PATCH endpoints:

Patient Upsert API Specification

Specification and Examples

PUT https://api.sandbox.zusapi.com/auth/patient/$upsert
NOTE: All attributes are required

{
    "data": {
        "attributes": {
            "patientIdentiferSystem":"<fhir identifier system>",
            "patient": {... the fhir/patient data },
            "user": {... the auth service user data}
        }
    }
}

The request body must have the following data points or the request will return an error:

  • attributes.patientIdentifierSystem - this is the identifier system used to look up the FHIR patient resource to check if it already exists before updating it or create a new resource.
  • attributes.patient request field must contain a FHIR patient identifier object that includes the patientIdentifierSystem above, because this specific identifier & system combination is used to look up the FHIR patient resource in Zus.
  • attributes.user must have userType set to "individual."

Example Request Body:

{
    "data": {
        "attributes": {
            "patientIdentifierSystem": "http://hospital.smarthealthit.org",
            "patient": {
                "resourceType": "Patient",
                "name": [
                    {
                        "family": "Smith",
                        "given": [
                            "Mike"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "system": "phone",
                        "value": "(999) 999-9999"
                    },
                    {
                        "system": "email",
                        "value": "[email protected]"
                    }
                ],
                "gender": "male",
                "birthDate": "1970-01-01",
                "address": [
                    {
                        "line": [
                            "101 Walnut St"
                        ],
                        "city": "Watertown",
                        "state": "MA",
                        "postalCode": "02472",
                        "country": "US"
                    }
                ],
                "communication": [
                    {
                        "language": {
                            "coding": [
                                {
                                    "system": "urn:ietf:bcp:47",
                                    "code": "en-US",
                                    "display": "English"
                                }
                            ],
                            "text": "English"
                        },
                        "preferred": true
                    }
                ],
                "identifier": [
                    {
                        "use": "usual",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                    "code": "MR",
                                    "display": "Medical Record Number"
                                }
                            ],
                            "text": "Medical Record Number"
                        },
                        "system": "http://hospital.smarthealthit.org",
                        "value": "1032702"
                    }
                ]
            },
            "user": {
                "data": {
                    "type": "auth/users",
                    "attributes": {
                        "email": "[email protected]",
                        "name": "John Smith",
                        "userType": "individual",
                        "sendPasswordResetEmail": false,
                        "sendVerificationEmail": false
                    },
                    "relationships": {
                        "auth/roles": {
                            "data": {
                                "type": "auth/roles",
                                "id": "{{RoleID}}"
                            }
                        }
                    }
                }
            }
        }
    }
}

You can see a sample API call and request body in the Zus Health Workspace in Postman: Zus Health API>Auth & Permissions>Auth Service API>User>Upsert Patient User.

Example Success Response:

  • Code = 201 if a new FHIR patient OR Auth Service user was created, 200 if no new resources were created.
  • Body = the auth service user (which has the FHIR patient resource ID on it)
{
  "data": {
    "type": "auth/users",
    "id:": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "attributes": {
      "createdAt": 0,
      "updatedAt": 0,
      "deletedAt": 0,
      "name": "string",
      "email": "string",
      "userType": "string"
    },
    "relationships": {
      "auth/roles": {
        "data": {
          "type": "auth/roles",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      },
      "fhir/Patient": {
        "data": {
          "type": "fhir/Patient",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  #patient FHIR resource ID from the patient resource upsert operation
        }
      }
    }
  }
}

Example Failure Responses:
The code/body from the FHIR request or Auth Service request that failed

FHIR 412 error:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "HAPI-0988: Failed to UPDATE resource with match URL \"Patient?identifier=https://zusapi.com/sarahs-test-identifier|1234\" because this search matched 2 resources"
        }
    ]
}

Auth Service 400 error:

[
    {
        "id": "70ac9e1a-3718-4e68-8de2-b735e6cb9bd7",
        "detail": "a user must have a user type"
    }
]

Logical flow