Enrollments

An enrollment represents a relationship between a consumer, installation, application, and application environment. Enrollments are used to authenticate a consumer to a unique installation of a ZSM client installed on a device. The ZSM API provides endpoints to manage enrollments.

Add an Enrollment

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

  • enrollment_id - A unique identifier for the enrollment.
  • consumer_id - A unique identifier for the consumer.
  • installation_id - A unique identifier for the installation on the device.
  • application_id - A unique identifier for the application.
  • environment - The environment for the enrollment. The environment must match one of the environment names configured for the corresponding application_id.
  • installation_description - A description of the installation.
$ curl -s -X POST \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
-H "Content-Type: application/json" \
-d '{"enrollment_id": "3d6f55b0-25c6-47b0-bcd6-283670c503fa", "consumer_id": "c87a9242-1afc-43b8-80e0-e4767c6f9c47", "installation_id": "cf282be7-7c15-456c-8dee-3fb450da9216", "application_id": "c8a75b96-c11f-4b44-a06d-6a638f3337e5", "environment": "TEST", "nickname": "Demo Enrollment"}' \
$ZSM_HOST/api/enrollments | jq
{
  "enrollment": {
    "enrollment_id": "3d6f55b0-25c6-47b0-bcd6-283670c503fa",
    "installation_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
    "consumer_id": "c87a9242-1afc-43b8-80e0-e4767c6f9c47",
    "application_id": "c8a75b96-c11f-4b44-a06d-6a638f3337e5",
    "environment": "TEST",
    "nickname": "Installation cf282be7-7c15-456c-8dee-3fb450da9216 Consumer c87a9242-1afc-43b8-80e0-e4767c6f9c47 using app c8a75b96-c11f-4b44-a06d-6a638f3337e5 in environment TEST",
    "active_keyset_id": null,
    "client_enclave_key": null,
    "client_storage_key_shares": null,
    "state": "active",
    "created": "2025-01-13 17:30:32.685855 +00:00",
    "modified": "2025-01-13 17:30:32.685855 +00:00"
  },
  "trace_id": "e7d95f5f-5141-40c5-9a49-7ca8687f8487"
}

Suspend an Enrollment

In the example below 00000000-0000-4000-b000-e00000000005 is an example enrollment identifier.

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

$ curl -s -X PATCH \
-H "Authorization: Bearer d4674d81-041c-497f-885a-f75aeeb3a491" \
"$ZSM_HOST/api/enrollments/00000000-0000-4000-b000-e00000000005"/suspend | jq
{
  "enrollment": {
    "enrollment_id": "00000000-0000-4000-b000-e00000000005",
    "installation_id": "00000000-0000-4000-b000-000000000006",
    "consumer_id": "00000000-0000-4000-b000-00000000000d",
    "application_id": "3dec4876-4c0b-43c7-96c5-9fea46ef0102",
    "environment": "TEST",
    "nickname": "Installation Five, Consumer 00000000000d",
    "active_keyset_id": null,
    "client_enclave_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEK4W77tb99mOE9GJhTpgow6C6b4Z8zkcCtppSaBzpZzJjheN9fmwGZUmxVC2msXO9lntDxBQ4pqJxnZF8sUjHxw==",
    "client_storage_key_shares": null,
    "state": "suspended",
    "created": "2023-06-21 14:17:15.715498 +00:00",
    "modified": "2025-01-13 16:53:14.074104 +00:00"
  },
  "trace_id": "e1a9884c-af3e-4ea7-aef6-ee67592e9dea"
}

Activate a Suspended Enrollment

In the example below 00000000-0000-4000-b000-e00000000005 is an example enrollment identifier.

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

$ curl -s -X PATCH \
-H "Authorization: Bearer d4674d81-041c-497f-885a-f75aeeb3a491" \
"$ZSM_HOST/api/enrollments/00000000-0000-4000-b000-e00000000005"/activate | jq
{
  "enrollment": {
    "enrollment_id": "00000000-0000-4000-b000-e00000000005",
    "installation_id": "00000000-0000-4000-b000-000000000006",
    "consumer_id": "00000000-0000-4000-b000-00000000000d",
    "application_id": "3dec4876-4c0b-43c7-96c5-9fea46ef0102",
    "environment": "TEST",
    "nickname": "Installation Five, Consumer 00000000000d",
    "active_keyset_id": null,
    "client_enclave_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEK4W77tb99mOE9GJhTpgow6C6b4Z8zkcCtppSaBzpZzJjheN9fmwGZUmxVC2msXO9lntDxBQ4pqJxnZF8sUjHxw==",
    "client_storage_key_shares": null,
    "state": "active",
    "created": "2023-06-21 14:17:15.715498 +00:00",
    "modified": "2025-01-13 16:53:44.959256 +00:00"
  },
  "trace_id": "332825ad-3f9c-43f9-9925-ba54835f7c79"
}

View a single Enrollment

$ curl -s \
-H "Authorization: Bearer d4674d81-041c-497f-885a-f75aeeb3a491" \
"$ZSM_HOST/api/enrollments/00000000-0000-4000-b000-e00000000005" | jq
{
  "enrollment": {
    "enrollment_id": "00000000-0000-4000-b000-e00000000005",
    "installation_id": "00000000-0000-4000-b000-000000000006",
    "consumer_id": "00000000-0000-4000-b000-00000000000d",
    "application_id": "3dec4876-4c0b-43c7-96c5-9fea46ef0102",
    "environment": "TEST",
    "nickname": "Installation Five, Consumer 00000000000d",
    "active_keyset_id": null,
    "client_enclave_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEK4W77tb99mOE9GJhTpgow6C6b4Z8zkcCtppSaBzpZzJjheN9fmwGZUmxVC2msXO9lntDxBQ4pqJxnZF8sUjHxw==",
    "client_storage_key_shares": null,
    "state": "active",
    "created": "2023-06-21 14:17:15.715498 +00:00",
    "modified": "2023-06-21 14:17:15.715498 +00:00"
  },
  "trace_id": "32efb41a-278d-438b-b301-1b0abf65fef9"
}

Retrieve All Enrollments

$ curl -s \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/enrollments | jq
{
  "enrollments": [
    {
      "enrollment_id": "00000000-0000-4000-b000-e00000000000",
      "installation_id": "00000000-0000-4000-b000-000000000000",
      "consumer_id": "00000000-0000-4000-b000-000000000002",
      "application_id": "3dec4876-4c0b-43c7-96c5-9fea46ef0102",
      "environment": "TEST",
      "nickname": "Installation One, Consumer 000000000002",
      "active_keyset_id": "6414d4579973d2e0c4754784f697da19600d6530fc047f00b6f9079a310ad5c5",
      "client_enclave_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEK4W77tb99mOE9GJhTpgow6C6b4Z8zkcCtppSaBzpZzJjheN9fmwGZUmxVC2msXO9lntDxBQ4pqJxnZF8sUjHxw==",
      "client_storage_key_shares": null,
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2025-01-09 20:32:26.664820 +00:00"
    },
    ...
    [truncated],
    ...
    {
      "enrollment_id": "00000000-0000-4000-b000-e00000000005",
      "installation_id": "00000000-0000-4000-b000-000000000006",
      "consumer_id": "00000000-0000-4000-b000-00000000000d",
      "application_id": "3dec4876-4c0b-43c7-96c5-9fea46ef0102",
      "environment": "TEST",
      "nickname": "Installation Five, Consumer 00000000000d",
      "active_keyset_id": null,
      "client_enclave_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEK4W77tb99mOE9GJhTpgow6C6b4Z8zkcCtppSaBzpZzJjheN9fmwGZUmxVC2msXO9lntDxBQ4pqJxnZF8sUjHxw==",
      "client_storage_key_shares": null,
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    }
  ],
  "total": 6,
  "page_size": 100
}