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

As with user accounts, your App Client access token will expire after an hour; you can update it using your refresh token. Your refresh token will expire after 30 days of use, or 15 days of inactivity.

To request a new token using your refresh token:

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":"refresh_token", "refresh_token":"YOUR_REFRESH_TOKEN"}'