Installations

Installations uniquely represent either hardware devices or an app in an instance of a browser. A device could therefore have multiple installations: a native app on that device, an app running under Chrome, and another app running under Safari.

Add an Installation

The /api/installations endpoint supports adding a new installation. The following JSON request body is required:

  • installation_id - The unique identifier for the installation. If an installation already exists, the existing installation will be returned.
  • description - A description of the installation.

The default state of an installation is unregistered. However, if the server has been built with the auto-verify feature. Or, if verification is provided through a third-party integration or other custom verification approach, devices may be automatically verified.

$ curl -s -X POST \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
-H "Content-Type: application/json" \
-d '{"installation_id": "cf282be7-7c15-456c-8dee-3fb450da9216", "description": "Test Installation"}' \
$ZSM_HOST/api/installations | jq
{
  "installation": {
    "installation_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
    "description": "Test Installation",
    "state": "verified",
    "created": "2025-01-10 21:13:01.689642 +00:00",
    "modified": "2025-01-10 21:13:01.689642 +00:00"
  },
  "trace_id": "3fbd139a-4ca5-4524-9b1a-d4363ffe0cbe"
}

View an Installation

In the example below cf282be7-7c15-456c-8dee-3fb450da9216 is an example installation identifier.

$ curl -s \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/installations/cf282be7-7c15-456c-8dee-3fb450da9216 | jq
{
  "installation": {
    "installation_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
    "description": "Test Installation",
    "state": "verified",
    "created": "2025-01-10 21:13:01.689642 +00:00",
    "modified": "2025-01-10 21:13:01.689642 +00:00"
  },
  "trace_id": "f6b11f77-e749-4f72-9f24-fd36cb83729e"
}

Update an Installation's Description

In the example below cf282be7-7c15-456c-8dee-3fb450da9216 is an example installation identifier.

When using the API, pass a JSON header body to the API and include in it a "description" key which the ZSM server uses to update the installation's description.

$ curl -s -X PATCH \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
-H "Content-Type: application/json" \
-d '{"description":"Revised Test Installation"}' \
$ZSM_HOST/api/installations/cf282be7-7c15-456c-8dee-3fb450da9216 | jq
{
  "installation": {
    "installation_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
    "description": "Revised Test Installation",
    "state": "verified",
    "created": "2025-01-10 21:13:01.689642 +00:00",
    "modified": "2025-01-10 21:19:40.477453 +00:00"
  },
  "trace_id": "d5938f3f-c581-4c8f-8eab-1d10db5e3fb1"
}

Suspend an Installation

In the example below cf282be7-7c15-456c-8dee-3fb450da9216 is an example installation identifier.

No JSON request body is required, and the "/suspend" path at the end of the request URL determines the action taken on the installation.

$ curl -s -X PATCH \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
$ZSM_HOST/api/installations/cf282be7-7c15-456c-8dee-3fb450da9216/suspend | jq
{
  "installation": {
    "installation_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
    "description": "Revised Test Installation",
    "state": "suspended",
    "created": "2025-01-10 21:13:01.689642 +00:00",
    "modified": "2025-01-10 21:21:18.367543 +00:00"
  },
  "trace_id": "dce727d3-693d-449b-b299-239131d5692c"
}

Re-verify a Suspended Installation

In the example below cf282be7-7c15-456c-8dee-3fb450da9216 is an example installation identifier.

No JSON request body is required, and the "/verify" path at the end of the request URL determines the action taken on the installation.

$ curl -s -X PATCH \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
$ZSM_HOST/api/installations/cf282be7-7c15-456c-8dee-3fb450da9216/verify | jq
{
  "installation": {
    "installation_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
    "description": "Revised Test Installation",
    "state": "verified",
    "created": "2025-01-10 21:13:01.689642 +00:00",
    "modified": "2025-01-10 21:26:11.444351 +00:00"
  },
  "trace_id": "d010ba99-2724-4ca8-94ae-299a2b2c1b62"
}

Retrieve Installations

The /api/installations endpoint supports retrieving a paginated list of installations filtered by various criteria. The following optional query parameters are supported:

  • organization_ids - The organization identifier(s) to filter installations by.
  • consumer_ids - The consumer identifier(s) to filter installations by.
  • installation_ids - The installation identifier(s) to filter installations by.
  • installation_description - The description of the installations(s) to filter by.
  • installation_desc_search_mode - The search mode for the installation description. Valid values are exact, contains, or startswith. Default is exact.
  • application_ids - The application identifier(s) to filter installations by.
  • enrollment_ids - The enrollment identifier(s) to filter installations by.
  • state - The state of the installations(s) to filter by. Valid values are active and suspended.
  • page - The page number to retrieve. If a page parameter is not provided, all consumers up to the default page_size will be returned. If paging is used, page indexing starts at 1.
  • page_size - The number of consumers to retrieve per page. Default is 100.
  • order - The order in which to sort the consumers. Valid values are asc and desc. Default is asc.

NOTE: With curl in some shells, be sure to quote the URL when using query parameters. Otherwise, the & will be interpreted as a request to run the command as a background process.

Retrieve installations by organization

In the example below bbc79d21-26d0-40c9-8334-2d95acdcbe1d is an example organization identifier. Also, pagination is demonstrated.

$ curl -s \
-H "Authorization: Bearer d4674d81-041c-497f-885a-f75aeeb3a491" \
"$ZSM_HOST/api/installations?organization_ids=bbc79d21-26d0-40c9-8334-2d95acdcbe1d&page=1&page_size=3" | jq
{
  "installations": [
    {
      "installation_id": "00000000-0000-4000-b000-000000000000",
      "description": "Test Installation One",
      "state": "verified",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    },
    {
      "installation_id": "00000000-0000-4000-b000-000000000003",
      "description": "Test Installation Two",
      "state": "verified",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    },
    {
      "installation_id": "00000000-0000-4000-b000-000000000004",
      "description": "Test Installation Three",
      "state": "verified",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    }
  ],
  "total": 6,
  "page": 1,
  "page_size": 3
}

Retrieve Installations by Consumers

In the example below, cf282be7-7c15-456c-8dee-3fb450da9216 and a52cf983-1da1-405f-8e02-18096252030a are example consumer identifiers.

$ curl -s - X GET -H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" $ZSM_HOST/api/installations?consumer_ids=cf282be7-7c15-456c-8dee-3fb450da9216&consumer_ids=a52cf983-1da1-405f-8e02-18096252030a | jq
{
  "installations": [
    {
      "installation_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
      "description": "Revised Demo Installation Name",
      "state": "verified",
      "created": "2023-10-24 17:18:52.689740 +00:00",
      "modified": "2023-10-24 17:23:41.302166 +00:00"
    },
    {
      "installation_id": "a52cf983-1da1-405f-8e02-18096252030a",
      "description": "Demo Installation",
      "state": "verified",
      "created": "2023-10-24 17:18:52.689740 +00:00",
      "modified": "2023-10-24 17:18:52.689740 +00:00"
    }
  ],
  "trace_id": "7a626fe9-ce25-4b87-8eb2-b12a7ee20143"
}