improved

April 15, 2022

On April 25, 2022, Zus Health will release a new version of the Auth Service API with new capabilities more closely aligned with the latest JSON v1.0 API spec. Please read on for details on breaking changes and rollout timeline.

The new Auth Service JSON API includes pagination and expanded filtering capabilities for all endpoints, as well as a new “include” parameter for getting information about related objects (e.g., get details about a user and their roles in one API call). Auth Service API objects now consist of attributes and relationships, resulting in breaking changes (see below). Zus will support the old and new API versions according to the rollout timeline below. This change does NOT affect any Zus APIs other than the Auth Service API.

Rollout Timeline:

  • April 15, 2022: New API version available for opt-in
  • April 25, 2022: New API version is the default, users can opt-out
  • May 9, 2022: New API is the only version available (opt-out period ends)

How to opt-in: Set the Content-Type API header to application/vnd.api+json.
How to opt-out: Set the Content-Type API header to application/legacy+5-9-2022.

If you have any questions or concerns about switching to using the new API version, please complete this support ticket form and select "Account log-in/authentication" for the question "What portion of the Zus Developer Sandbox does your support ticket relate to?"

Breaking changes:

  • The IdentityRoleLink object is no longer available, as users can be assigned to roles directly through the POST User endpoint.
  • Casing changes
    • Object field names are camel case (e.g., RoleID instead of role_id)
    • URL terms are kebab case (e.g., app-clients instead of appclients)
  • Model structure changes for all objects: fields other than type or id are now modeled as attributes of the object or relationships to the object. Example:
{
  "type": "auth/users",
  "id": <UUID>,
  "attributes": {
    "email": <string>,
    "name": <string>,
    "userType": <string>
  }, 
  "relationships": {
    "role": {
      "data": { "type": "auth/roles", "id": <UUID> }
    }, 
    "practitioner": {
      "data": { "type": "fhir/practitioner", "id": <UUID> }
    }
  }
}