Product Guide

Creating Users

Suggest Edits

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

Creating 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)

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

Managing Practitioner Users

Overview

If you have users that need to be linked to corresponding FHIR Practitioner resources, you can use our Practitioner Upsert APIs to do so. For example, a clinical user can be linked to a Practitioner resource so that patient data they create or update can be tied back to their practitioner. You can use the Practitioner User Upsert API endpoint to create & update users, create & update Practitioner resources, and link the two together.

Practitioner User Upsert API

The Practitioner User Upsert endpoint performs upsert operations on a FHIR Practitioner resource and the user linked to that Practitioner 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 Practitioner resources and users
  • Simultaneous PUT updates to BOTH Practitioner resources and users, ensuring Practitioner resources and the users they are linked to stay in sync

To make changes to only the Practitioner resource or only the user, use the appropriate PUT or PATCH endpoints:

Practitioner User Upsert API Specification

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

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

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

  • attributes.practitionerIdentifierSystem this is the identifier system used to look up the Practitioner resource to check if it already exists before updating it or create a new resource.
  • attributes.practitioner request field must contain a Practitioner identifier object that includes the practitionerIdentifierSystem above, because this specific identifier & system combination is used to look up the Practitioner resource.
  • attributes.user must have userType set to "builder."

Example Request Body:

{
    "data": {
        "attributes": {
            "practitionerIdentifierSystem": "http://hospital.smarthealthit.org",
            "practitioner": {
                "resourceType": "Practitioner",
                "text": {
                    "status": "generated",
                    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\n      <p>Dr Adam Careful is a Referring Practitioner for Acme Hospital from 1-Jan 2012 to 31-Mar\n        2012</p>\n    </div>"
                },
                "identifier": [
                    {
                        "use": "official",
                        "system": "http://hospital.smarthealthit.org",
                        "value": "991032702992299"
                    }
                ],
                "active": true,
                "name": [
                    {
                        "family": "Flubegone",
                        "given": [
                            "Debra"
                        ],
                        "prefix": [
                            "Dr"
                        ]
                    }
                ],
                "address": [
                    {
                        "use": "home",
                        "line": [
                            "534 Erewhon St"
                        ],
                        "city": "PleasantVille",
                        "state": "Vic",
                        "postalCode": "3999"
                    }
                ],
                "qualification": [
                    {
                        "identifier": [
                            {
                                "system": "http://example.org/UniversityIdentifier",
                                "value": "12345"
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v2-0360/2.7",
                                    "code": "BS",
                                    "display": "Bachelor of Science"
                                }
                            ],
                            "text": "Bachelor of Science"
                        },
                        "period": {
                            "start": "1995"
                        },
                        "issuer": {
                            "display": "Example University"
                        }
                    }
                ]
            },
            "user": {
                "data": {
                    "type": "auth/users",
                    "attributes": {
                        "email": "debra.flubegone@primarycare.com",
                        "name": "Debra Flubegone M.D.",
                        "userType": "builder",
                        "sendPasswordResetEmail": 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 Practitioner User.

Example Success Response:

  • Code = 201 if a new Practitioner OR user was created, 200 if no new resources were created.
  • Body = the user (which has the Practitioner resource ID on it)
{
    "data": {
        "type": "auth/users",
        "id": "3d81a0ca-3e72-429d-9459-ed43d83802d9",
        "attributes": {
            "createdAt": 1670597992,
            "email": "debra.flubegone@primarycare.com",
            "name": "Debra Flubegone M.D.",
            "updatedAt": 1670597992,
            "userType": "builder"
        },
        "relationships": {
            "auth/builders": {
                "data": {
                    "type": "auth/builders",
                    "id": "c1e40956-7808-4063-9f43-49370f3c8ddb"
                }
            },
            "auth/roles": {
                "data": {
                    "type": "auth/roles",
                    "id": "23b56d6c-eb02-426f-9034-a8a90a599ca3"
                }
            },
            "fhir/practitioner": {
                "data": {
                    "type": "fhir/practitioner",
                    "id": "19c21c89-c0c4-49d6-9aa3-f88228d3a9f4" #FHIR Practitioner resource ID from the Practitioner resource upsert operation
                }
            }
        }
    }
}

Logical flow

Updated 6 days ago