Organization API

REST API endpoints exist to list all organizations, view a single organization, add a new organization, update an organization's description, suspend an organization, and activate a suspended organization.

List All Organizations

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

$ curl -s \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/organizations | jq
{
  "organizations": [
    {
      "organization_id": "bbc79d21-26d0-40c9-8334-2d95acdcbe1d",
      "description": "Ideem",
      "state": "active",
      "created": "2023-09-18 14:46:10.493234 +00:00",
      "modified": "2023-10-19 01:02:57.013323 +00:00"
    },
    {
      "organization_id": "f954b94a-8e3c-438f-95e4-d5f87c9eb570",
      "description": "Better Test Customer Name",
      "state": "active",
      "created": "2023-10-23 16:57:48.409535 +00:00",
      "modified": "2023-10-23 17:00:56.323171 +00:00"
    }
  ],
  "trace_id": "f2fcd04c-f469-4ee4-992a-b93bc0ad4804"
}

View an Organization

In the example below 'f954b94a-8e3c-438f-95e4-d5f87c9eb570' is an example organization identifier.

$ curl -s \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/organizations/f954b94a-8e3c-438f-95e4-d5f87c9eb570 | jq
{
  "organization": {
    "organization_id": "f954b94a-8e3c-438f-95e4-d5f87c9eb570",
    "description": "Better Test Customer Name",
    "state": "active",
    "created": "2023-10-23 16:57:48.409535 +00:00",
    "modified": "2023-10-23 17:00:56.323171 +00:00"
  },
  "trace_id": "950da3ec-9ac7-4172-b032-80d0ce99275d"
}

Add a New Organization

Vendor organizations create new customer and partner organizations using the POST /api/organizations REST API. Customer organizations also use this same endpoint to create their own partner organizations. Partners cannot create new organizations of any kind.

The API must be called using a bearer token that has been issued to the organization using the ZSM Server CLI. The token must be issued with the admin role. See Authentication Token Management for more information.

In all scenarios, the JSON request body must contain a "description" key whose value then becomes the description or name of the new organization.

Example of a vendor organization adding a new customer organization with supported environments:

A vendor organization creates a new customer by calling the POST /api/organizations API using a bearer token issued to them with administrative rights and passing their own (the vendor's) organization_id as the value in a parent_id key in the request body.

If the vendor wants to allow the customer to use virtual environments for the customer's applications, then a supported_environments object which contains a list of supported environments and which environment is the default is also added to the request body. If the vendor does not include a supported_environments object, the new customer will be unable to use virtual application environments

NOTE: The ZSM server does not support enabling virtual application environments, nor does it support disabling them, once a customer organization has been created. The decision on whether to support virtual application environments must be made when the customer organization is first created.

In this following example, 401964e2-6ded-45fa-a233-cebdff44806a is a bearer token with the admin role issued to the vendor whose organization_id is 2bdd119f-302c-4589-8026-90ab4f7171b0:

$ curl -s -X POST \
-H "Authorization: Bearer 401964e2-6ded-45fa-a233-cebdff44806a" \
-H "Content-Type: application/json" \
-d '{"parent_id":"2bdd119f-302c-4589-8026-90ab4f7171b0", "description":"Newer Customer With Environments", \
     "supported_environments":{"default":"TEST","supported":"DEMO,TEST,PROD"}}' \
https://localhost:3000/api/organizations | jq
{
  "organization": {
    "organization_id": "a504d11b-a2a4-40e6-a17c-2132028dff5a",
    "parent_id": "2bdd119f-302c-4589-8026-90ab4f7171b0",
    "organization_type": "customer",
    "description": "Newer Customer With Environments",
    "state": "active",
    "supported_environments": {
      "default": "TEST",
      "supported": "DEMO,PROD,TEST"
    },
    "created": "2025-04-21 19:14:27.653348 +00:00",
    "modified": "2025-04-21 19:14:27.653348 +00:00"
  },
  "trace_id": "ea3bb807-8596-4147-9dfd-9e6aa9df4c92"
}

Example of the vendor organization adding a new customer organization that does not use virtual application environments:

A vendor organization creates a new customer that does not use virtual application environments by calling the POST /api/organizations API using a bearer token issued to them with administrative rights and passing their own (the vendor's) organization_id as the value in a parent_id key in the request body.

If the vendor does not include a supported_environments object, the new customer will be unable to use virtual application environments

NOTE: The ZSM server does not support enabling virtual application environments, nor does it support disabling them, once a customer organization has been created. The decision on whether to support virtual application environments must be made when the customer organization is first created.

In this following example, 401964e2-6ded-45fa-a233-cebdff44806a is a bearer token with the admin role issued to the vendor whose organization_id is 2bdd119f-302c-4589-8026-90ab4f7171b0:

$ curl -s -X POST \
-H "Authorization: Bearer 401964e2-6ded-45fa-a233-cebdff44806a" \
-H "Content-Type: application/json" \
-d '{"parent_id":"2bdd119f-302c-4589-8026-90ab4f7171b0", "description":"Newer Customer With No Environments"}}' \
https://localhost:3000/api/organizations | jq
{
  "organization": {
    "organization_id": "50e11053-cd0d-4740-aa38-5a86123b4e7a",
    "parent_id": "2bdd119f-302c-4589-8026-90ab4f7171b0",
    "organization_type": "customer",
    "description": "Newer Customer With No Environments",
    "state": "active",
    "created": "2025-04-21 19:16:19.424540 +00:00",
    "modified": "2025-04-21 19:16:19.424540 +00:00"
  },
  "trace_id": "154c7ebf-dd6a-4f81-ba98-514ccc43683b"
}

Example of the vendor organization adding a new partner organization associated with a customer:

A vendor organization creates a new partner organization associated with an existing customer organization by calling the POST /api/organizations API using a bearer token issued to them with administrative rights and passing the organization_id of the customer organization with which the partner organization will be associated.

In this following example, 401964e2-6ded-45fa-a233-cebdff44806a is a bearer token with the admin role issued to the vendor. And, 50e11053-cd0d-4740-aa38-5a86123b4e7 is the organization_id of the customer organization under whom the new partner organization will be associated.

curl -s -X POST \
-H "Authorization: Bearer 401964e2-6ded-45fa-a233-cebdff44806a" \
-H "Content-Type: application/json" \
-d '{"parent_id":"50e11053-cd0d-4740-aa38-5a86123b4e7a", "description":"Newer Partner Organization"}' \
https://localhost:3000/api/organizations | jq
{
  "organization": {
    "organization_id": "0a1dacac-d599-4e60-a789-69da59735843",
    "parent_id": "50e11053-cd0d-4740-aa38-5a86123b4e7a",
    "organization_type": "partner",
    "description": "Newer Partner Organization",
    "state": "active",
    "created": "2025-04-21 19:18:44.344165 +00:00",
    "modified": "2025-04-21 19:18:44.344165 +00:00"
  },
  "trace_id": "3c946061-64a1-4acc-a8c4-173dbcd5ea9a"
}

A customer organization adding a new partner:

A customer organization creates an associated new partner organization by calling the POST /api/organizations API using a bearer token issued to them with administrative rights. The caller does not pass a parent_id in this scenario as the server knows the customer to which the bearer token was assigned and automatically associates the new partner organization with that customer.

In this following example, 1b0bb6dd-f5df-4d51-99c2-99abca7d49dd is a bearer token with the admin role issued to the customer organization under whom the new partner organization will be associated.

$ curl -s -X POST \
-H "Authorization: Bearer 1b0bb6dd-f5df-4d51-99c2-99abca7d49dd" \
-H "Content-Type: application/json" \
-d '{"description":"Newer Partner Organization"}' https://localhost:3000/api/organizations | jq
{
  "organization": {
    "organization_id": "82111898-e7eb-4ad8-b65d-b556fd56cb09",
    "parent_id": "50e11053-cd0d-4740-aa38-5a86123b4e7a",
    "organization_type": "partner",
    "description": "Newer Partner Organization",
    "state": "active",
    "created": "2025-04-21 19:20:40.690296 +00:00",
    "modified": "2025-04-21 19:20:40.690296 +00:00"
  },
  "trace_id": "51b11972-2122-44b3-97a4-6e6ed7a73146"
}

Update an Organization's Description

In the example below bbc79d21-26d0-40c9-8334-2d95acdcbe1d is an example organization 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 organization's description.

$ curl -s -X PATCH \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
-H "Content-Type: application/json" \
-d '{"description":"Revised Customer Name"}' \
$ZSM_HOST/api/organizations/bbc79d21-26d0-40c9-8334-2d95acdcbe1d | jq
{
  "organization": {
    "organization_id": "bbc79d21-26d0-40c9-8334-2d95acdcbe1d",
    "parent_id": "178588b1-8962-4b2c-b97a-e5371f353ae9",
    "organization_type": "customer",
    "description": "Revised Customer Name",
    "state": "active",
    "created": "2023-09-18 14:46:10.493234 +00:00",
    "modified": "2025-01-10 16:17:41.797793 +00:00"
  },
  "trace_id": "73d97714-2c9b-469b-9cf8-733721d6e297"
}

Suspend an Organization

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

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

$ curl -s -X PATCH \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/organizations/2746c097-3e8a-4f46-80ba-be68c377b4e9/suspend | jq
{
  "organization": {
    "organization_id": "bbc79d21-26d0-40c9-8334-2d95acdcbe1d",
    "parent_id": "178588b1-8962-4b2c-b97a-e5371f353ae9",
    "organization_type": "customer",
    "description": "Revised Customer Name",
    "state": "suspended",
    "created": "2023-09-18 14:46:10.493234 +00:00",
    "modified": "2025-01-10 16:19:37.581064 +00:00"
  },
  "trace_id": "00cf6a34-ff97-421b-bb57-27513c86983c"
}

Activate a Suspended Organization

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

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

$ curl -s -X PATCH \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/organizations/2746c097-3e8a-4f46-80ba-be68c377b4e9/activate | jq
{
  "organization": {
    "organization_id": "bbc79d21-26d0-40c9-8334-2d95acdcbe1d",
    "parent_id": "178588b1-8962-4b2c-b97a-e5371f353ae9",
    "organization_type": "customer",
    "description": "Revised Customer Name",
    "state": "active",
    "created": "2023-09-18 14:46:10.493234 +00:00",
    "modified": "2025-01-10 16:19:48.375166 +00:00"
  },
  "trace_id": "052c3e54-0e52-4e37-a85f-e8457be33745"
}

View Supported Environments for an Organization

In the example below 'bbc79d21-26d0-40c9-8334-2d95acdcbe1d' is an example organization identifier.

$ curl -s \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
$ZSM_HOST/api/organizations/bbc79d21-26d0-40c9-8334-2d95acdcbe1d/environments | jq
{
  "organization_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
  "default": "TEST"
  "supported": "TEST",
  "trace_id": "2479c3a9-55b5-4120-afec-dcba9cb224e6"
}

Set the Default Environment for an Organization

In the example below 'bbc79d21-26d0-40c9-8334-2d95acdcbe1d' is an example organization identifier.

$ curl -s -X PATCH \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
-H "Content-Type: application/json" \
-d '{"default":"DEMO"}' \
$ZSM_HOST/api/organizations/bbc79d21-26d0-40c9-8334-2d95acdcbe1d/environments | jq
{
  "organization_id": "cf282be7-7c15-456c-8dee-3fb450da9216",
  "default": "DEMO"
  "supported": "DEMO,TEST"
  "trace_id": "2479c3a9-55b5-4120-afec-dcba9cb224e6"
}

Add New Supported Environments to an Organization

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 PATCH \
-H "Authorization: Bearer 50563d0c-e487-4822-96d8-4af26ef35d38" \
-H "Content-Type: application/json" \
-d '{"environment":"PROD"}' \
$ZSM_HOST/api/organizations/bbc79d21-26d0-40c9-8334-2d95acdcbe1d/environments | jq
{
  "application_id": "3dec4876-4c0b-43c7-96c5-9fea46ef0102",
  "default": "DEMO"
  "supported": "DEMO,PROD,TEST"
  "trace_id": "3399ae5e-056b-43a0-b4be-0c1d1962e707"
}

Remove an Environment from an Organization

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 3dec4876-4c0b-43c7-96c5-9fea46ef0102.

$ curl -s -X DELETE \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
-H "Content-Type: application/json" \
-d '{"environment":"TEST"}' \
ZSM_HOST/api/organizations/bbc79d21-26d0-40c9-8334-2d95acdcbe1d/environments | jq
{
  "application_id": "3dec4876-4c0b-43c7-96c5-9fea46ef0102",
  "default": "DEMO"
  "supported": "DEMO,PROD"
  "trace_id": "55ad1d42-f226-4b38-9f9a-422863fe0eb4"
}