Creating 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.
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.
{
"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
tofalse
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.
{
"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
}
}
}
}
}
Updated 7 days ago