Machine-to-Machine

This tutorial will guide you through setting up a Machine-to-Machine App Client and connecting to Zus, allowing your backend application to read and write data to Zus.

You can try out steps 1-3 below in the Zus Health API Postman collection by navigating to the M2M App Client Creation Guide in the Auth & Permissions folder.

Step 1: Specify a Role for the App Client

Specify the role you want the App Client 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. For Machine-to-Machine App Clients, we recommend the Builder Admin role.

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

Then extract the id from the response. Save this value to be used in the next request.

{
    "data": {
        "type": "auth/roles",
        "id": "<RoleID>", #for step 2
        "attributes": {
            "createdAt": timestamp,
            "description": "<description>",
            "isManaged": true,
            "name": "<RoleName>",
            "permissions": [
              #permissions listed here
            ],
            "updatedAt": timestamp
        }
    }
}

Step 2: Create an App Client in the Auth Service

Create app client documentation

POST https://api.sandbox.zusapi.com/auth/app-clients

{
    "data": {
        "type": "auth/app-clients",
        "attributes": {
            "type": "machine_to_machine",
            "name": "{{AppClientName}}",
            "userType": "builder"
        },
        "relationships": {
            "auth/roles": {
                "data": {
                    "type": "auth/roles",
                    "id": "{{RoleID}}" #from step 1
                }
            }
        }
    }
}

Save the id, clientId and clientSecret of your app client from the response body.

If you didn't save the clientSecret, or need to change it, you can use the rotate-secret endpoint to change the clientSecret.

Step 3: Request an access token

Machine-to-Machine App Clients can use the Client Credentials Flow to request an access token using the following API request:

Parameter	Value
`grant_type`	client_credentials
`client_id`	Your App Client's "clientId" returned when you first created the App Client in Zus.
`client_secret`	Your App Client's "clientSecret" returned when you first created the App Client in Zus.
`audience`	https://api.sandbox.zusapi.com

cURL example:

curl --request POST \
  --url https://auth.sandbox.zusapi.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_APPCLIENT_ID","client_secret":"YOUR_APPCLIENT_SECRET","audience":"https://api.sandbox.zusapi.com","grant_type":"client_credentials"}'

response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"YOUR_APPCLIENT_ACCESS_TOKEN",
  "expires_in":3600,
  "token_type":"Bearer"
}

Step 4: Make an API Call with the Access Token

cURL example:

request:

curl --request GET \
     --url https://api.sandbox.zusapi.com/auth/app-clients/<YOUR_APPCLIENT_UUID>\
     --header 'Accept: application/vnd.api+json' \
     --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

response:

{
  "data": {
    "type": "auth/app-clients",
    "id": "YOUR_APPCLIENT_UUID",
    "attributes": {
      "clientId": "YOUR_APPCLIENT_ID (for authentication)",
      "createdAt": 1651254340,
      "name": "YOUR_APPCLIENT_NAME",
      "type": "machine_to_machine",
      "updatedAt": 1651254340,
      "userType": "builder"
    },
    "relationships": {
      "auth/roles": {
        "data": {
          "type": "auth/roles",
          "id": "ROLE_UUID"
        }
      }
    }
  }
}

Access Token Expiry

Your machine-to-machine access token will expire after an hour. At which point, your application should request a new access token using the request shown in the "Request an access token" step.

Token authentication is subject to a special rate limit, as calling systems are expected to acquire a token and continue to use it until it expires. If your application attempts to obtain a token for the same app client more than 200 times in an hour, the application will receive a 429 error.