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.

Creating Users in the App

In the Zus App you can create and manage users via the "Users" page in the Admin Settings.

This page allows you to view, add, and edit users. Today, deleting users is not possible from this page.

Only Builder Admin users can create new users on this page.

Creating Users via API

📘

For assistance with the steps below, check out the User Creation Guide in the Zus Health Postman Collection.

Step 1: Create a Practitioner Resource (Optional)

If you have clinical users, Zus allows you to optionally create a FHIR Practitioner resource for your users and link this Practitioner resource to their identity. You can then associate that FHIR Practitioner resource with FHIR Care Teams and PractitionerRoles.

This Practitioner resource 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.

📘

New users to Zus’s sandbox environment will receive a welcome email with links to our apps and documentation to help them get started in the sandbox. New users in the production environment will not receive a welcome email.

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