Application and Application Environments API

REST API endpoints exist to list all applications, view a single application, register a new application, update an existing application's description, suspend an application, and activate a suspended application.

If a customer is enabled to support virtual application environments, additional REST API endpoints exist to view the environments associated with an application, add a new environment to the list, and to remove an environment from the list. Whenever a new application is created, if no environments are specified, it is created with the default for the customer. Each application must always have at least one environment defined. An environment cannot be removed once one or more keysets have been generated for an enrollment for that application within the environment. Environment names are not case-sensitive and are always stored and displayed in uppercase. If a customer is not enabled to support virtual application environments, these endpoints are not available and the allowed_environments attribute is not returned for applications associated with the customer.

List All Applications

The application results are automatically filtered based upon the bearer token. If the token was issued to the vendor organization, all applications will be included. But if the token was issued to a customer, only applications associated with that customer will be listed. If the token was issued to a partner, the partner's customer's applications will be listed.

The applications array will be empty if no applications exist for the vendor or customer.

In the example below, organization 352baf02-adc3-4aed-8254-73f8677fc5a2 has only registered a single organization, and the API call is being made using a bearer token associated with that organization.

$ curl -s \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
$ZSM_HOST/api/applications | jq
{
  "applications": [
    {
      "application_id": "c8a75b96-c11f-4b44-a06d-6a638f3337e5",
      "organization_id": "352baf02-adc3-4aed-8254-73f8677fc5a2",
      "description": "Demo CLI Client",
      "allowed_environments": "TEST",
      "state": "active",
      "created": "2025-01-10 15:43:16.371796 +00:00",
      "modified": "2025-01-10 15:43:16.371796 +00:00"
    }
  ],
  "trace_id": "1d1ad8a2-8efa-4f71-ad9f-0f9a42e497b9"
}

View an Application

In the example below '3dec4876-4c0b-43c7-96c5-9fea46ef0102' is an example application identifier.

$ curl -s \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/applications/3dec4876-4c0b-43c7-96c5-9fea46ef0102 | jq
{
  "application": {
    "application_id": "3dec4876-4c0b-43c7-96c5-9fea46ef0102",
    "organization_id": "bbc79d21-26d0-40c9-8334-2d95acdcbe1d",
    "description": "Demo CLI Client",
    "allowed_environments": "TEST",
    "state": "active",
    "created": "2023-09-18 14:46:10.493234 +00:00",
    "modified": "2023-10-18 00:36:50.876753 +00:00"
  },
  "trace_id": "1b9d2b0a-771f-4100-b1a7-c20cef924eaf"
}

Register a New Application

In the example below, a JSON body is passed to the API. It must contain a "description" key whose value then becomes the description or name of the new application. It must also contain an "organization_id" key whose value is the customer organization identifier to which the application will be registered. In this example, it is bbc79d21-26d0-40c9-8334-2d95acdcbe1d.

The bearer token used to authenticate to this API must be issued to either the vendor or the customer and have either the administrator or application administrator role. Partner organizations cannot register new applications.

The JSON body may also optionally contain an "application_id" key. If provided and an application with that identifier is not already registered, the new application will be registered using the provided identifier. Otherwise, a random identifier will be assigned. ZSM uses UUIDs for application identifiers. If the developer has a non-UUID application identifier, they should hash what they have into a UUID (MD5 could be used for this purpose).

Example where only the organization identifier and a description are provided:

$ curl -s -X POST \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
-H "Content-Type: application/json" \
-d '{"organization_id":"352baf02-adc3-4aed-8254-73f8677fc5a2", "description":"New Demo Application"}' \
$ZSM_HOST/api/applications | jq
{
  "application": {
    "application_id": "8e548083-f1bd-4b76-8d83-e8f03c1dec2a",
    "organization_id": "352baf02-adc3-4aed-8254-73f8677fc5a2",
    "description": "New Demo Application",
    "allowed_environments": "TEST",
    "state": "active",
    "created": "2025-01-10 16:47:03.277547 +00:00",
    "modified": "2025-01-10 16:47:03.277547 +00:00"
  },
  "trace_id": "6b7a4526-e862-4e72-8f64-1d32f4c65de0"
}

Example where an application identifier, specifically aacac7c4-7305-4372-88c4-62c1a9a3c285, is also provided:

$ curl -s -X POST \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
-H "Content-Type: application/json" \
-d '{"organization_id":"352baf02-adc3-4aed-8254-73f8677fc5a2", "application_id":"aacac7c4-7305-4372-88c4-62c1a9a3c285", "description":"New Demo Application"}' \
$ZSM_HOST/api/applications | jq
{
  "application": {
    "application_id": "aacac7c4-7305-4372-88c4-62c1a9a3c285",
    "organization_id": "352baf02-adc3-4aed-8254-73f8677fc5a2",
    "description": "New Demo Application",
    "allowed_environments": "TEST",
    "state": "active",
    "created": "2025-01-10 16:49:36.188732 +00:00",
    "modified": "2025-01-10 16:49:36.188732 +00:00"
  },
  "trace_id": "96820f56-5fec-41c6-bd5a-c5ce3a15e495"
}

Update an Application Description

In the example below 'cf282be7-7c15-456c-8dee-3fb450da9216' is an example application identifier. And, a JSON header body is passed to the API. It must contain a "description" key whose value is then used to update the application's description.

$ curl -s -X PATCH \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
-H "Content-Type: application/json" \
-d '{"description":"Revised Demo Application Name"}' \
$ZSM_HOST/api/applications/aacac7c4-7305-4372-88c4-62c1a9a3c285 | jq
{
  "application": {
    "application_id": "aacac7c4-7305-4372-88c4-62c1a9a3c285",
    "organization_id": "352baf02-adc3-4aed-8254-73f8677fc5a2",
    "description": "Revised Demo Application Name",
    "allowed_environments": "TEST",
    "state": "active",
    "created": "2025-01-10 16:49:36.188732 +00:00",
    "modified": "2025-01-10 16:54:40.395668 +00:00"
  },
  "trace_id": "7b7acdc6-bec2-4568-b5cf-b7ae0cf984ea"
}

Suspend an Application

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

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

$ curl -s -X PATCH \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/applications/cf282be7-7c15-456c-8dee-3fb450da9216/suspend | jq
{
  "application": {
    "application_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
    "organization_id": "bbc79d21-26d0-40c9-8334-2d95acdcbe1d",
    "description": "Revised Demonstration Application",
    "allowed_environments": "TEST",
    "state": "suspended",
    "created": "2023-10-24 17:18:52.689740 +00:00",
    "modified": "2023-10-24 17:23:10.670876 +00:00"
  },
  "trace_id": "8f992467-2cbb-4b3f-a298-f7dea7bed158"
}

Activate a Suspended Application

In the example below 'cf282be7-7c15-456c-8dee-3fb450da9216' is an example application identifier. No JSON request body is required, and the "/activate" path at the end of the request URL determines the action taken on the application.

$ curl -s -X PATCH \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/applications/cf282be7-7c15-456c-8dee-3fb450da9216/activate | jq
{
  "application": {
    "application_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
    "organization_id": "bbc79d21-26d0-40c9-8334-2d95acdcbe1d",
    "description": "Revised Demonstration Application",
    "allowed_environments": "TEST",
    "state": "active",
    "created": "2023-10-24 17:18:52.689740 +00:00",
    "modified": "2023-10-24 17:23:41.302166 +00:00"
  },
  "trace_id": "7a626fe9-ce25-4b87-8eb2-b12a7ee20143"
}

View Application Environments

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

$ curl -s \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/environments/cf282be7-7c15-456c-8dee-3fb450da9216 | jq
{
  "application_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
  "environments": "TEST",
  "trace_id": "2479c3a9-55b5-4120-afec-dcba9cb224e6"
}

Add a New Environment to an Application

In the example below, a JSON header body is passed to the API. It must contain an "environment" key whose value is the name of the environment to be added to the environment list for the specified application. In this example, the application identifier is 3dec4876-4c0b-43c7-96c5-9fea46ef0102.

$ curl -s -X POST \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
-H "Content-Type: application/json" \
-d '{"environment":"DEMO"}' \
$ZSM_HOST/api/environments/3dec4876-4c0b-43c7-96c5-9fea46ef0102 | jq
{
  "application_id": "3dec4876-4c0b-43c7-96c5-9fea46ef0102",
  "environments": "DEMO,TEST",
  "message": "DEMO environment added to application",
  "trace_id": "3399ae5e-056b-43a0-b4be-0c1d1962e707"
}

Remove an Environment from an Application

In the example below, a JSON header body is passed to the API. It must contain an "environment" key whose value is the name of the environment to be removed from the environment list for the specified application. In this example the application identifier is aacac7c4-7305-4372-88c4-62c1a9a3c285.

$ curl -s -X DELETE \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
-H "Content-Type: application/json" \
-d '{"environment":"TEST"}' \
ZSM_HOST/api/environments/aacac7c4-7305-4372-88c4-62c1a9a3c285 | jq
{
  "application_id": "aacac7c4-7305-4372-88c4-62c1a9a3c285",
  "environments": "DEMO",
  "trace_id": "55ad1d42-f226-4b38-9f9a-422863fe0eb4"
}