IP Access Allowlist Configuration

The following API commands enable you to use allowlists to control access to the endpoints of your Control-M SaaS tenants. Each allowlist defines a group of IPv4 addresses that are allowed to access your endpoints. Any request from an IP address that does not appear in the activated allowlists is blocked at the network edge, even before authentication is processed.

For more information, see Network Access Management.

config systemsettings:allowlists::add

The config systemsettings:allowlists::add command enables you to create a new allowlist, which lists IP addresses that are allowed to access the endpoints of your Control-M SaaS tenant.

You can create up to a maximum of 50 allowlists per Control-M SaaS tenant.

  • CLI

  • REST

ctm config systemsettings:allowlists::add -f <configuration file>

The following example shows the REST API syntax for the config systemsettings:allowlists::add command in cURL:

Copy 
curl -H "x-api-key: $token" -f "NY_Access.json"
-X POST "$endpoint/config/systemsettings/allowlists"

where configuration file defines a pathname to a JSON file that contains allowlist definitions, as shown in the following example:

Copy 
{
   "allowlistName": "office-network",
   "description": "The back office site in New York",
   "ipType": "ipv4",
   "ipAddresses": [
      "234.0.123.10/32",
      "234.0.123.0/24",
      "234.0.123.4/16"
   ]
}

The following table describes the properties in this configuration file:

Property

Description

allowlistName

Defines the name of the allowlist.

description

Defines a textual description for the allowlist.

ipType

Determines the IP address protocol.

Currently, only ipv4 is supported.

ipAddresses

Lists the IP addresses to include in the allowlist, in an array format.

This array can include up to 15 IP addresses.

These IP addresses are granted permission to access the endpoints of your Control-M SaaS tenant.

config systemsettings:allowlists:enable::set

The config systemsettings:allowlists:enable::set command enables you to activate one or more allowlists and start using them to limit access to your endpoints.

To prevent you from mistakenly locking yourself out

  • When no allowlists are active and you activate your first allowlist, your current IP address must be included in the allowlist.

  • You must complete the enable process by running the config systemsettings:allowlists:acknowledge command between one and two minutes after you run the config systemsettings:allowlists:enable::set command. If you fail to acknowledge, the enable process reverts automatically.

  • CLI

  • REST

ctm config systemsettings:allowlists:enable::set -f <configuration file>

where configuration file defines a pathname to a JSON file that contains an array of allowlists that you want to enable, as shown in the following example:

Copy 
{
   "allowlistIds": ["wl-12345", "wl-12346", "wl-12347"]
}

Each allowlist is identified by its allowListId, which is an automatically generated ID that differs from the allowlist name. You can obtain this ID by running the config systemsettings:allowlists::get command.

The following example shows the REST API syntax for the config systemsettings:allowlists:enable::set command in cURL:

Copy 
curl -H "x-api-key: $token" -X POST
-d "{\"allowlistIds\": [\"wl-12345","wl-12346"]}"
"$endpoint/config/systemsettings/allowlists/enable"

You provide the list of allowlists to enable through the body. Each allowlist is identified by its allowListId, which is an automatically generated ID that differs from the allowlist name. You can obtain this ID by running the config systemsettings:allowlists::get command.

config systemsettings:allowlists:disable::set

The config systemsettings:allowlists:disable::set command enables you to deactivate one or more allowlists and stop using them to limit access to your endpoints.

To prevent you from mistakenly locking yourself out, you must complete the disable process by running the config systemsettings:allowlists:acknowledge command between one and two minutes after you run the config systemsettings:allowlists:disable::set command. If you fail to acknowledge, the disable process reverts automatically.

  • CLI

  • REST

ctm config systemsettings:allowlists:disable::set -f <configuration file>

where configuration file defines a pathname to a JSON file that contains an array of allowlists that you want to disable, as shown in the following example:

Copy 
{
   "allowlistIds": ["wl-12345", "wl-12346", "wl-12347"]
}

Each allowlist is identified by its allowListId, which is an automatically generated ID that differs from the allowlist name. You can obtain this ID by running the config systemsettings:allowlists::get command.

The following example shows the REST API syntax for the config systemsettings:allowlists:disable::set command in cURL:

Copy 
curl -H "x-api-key: $token" -X POST
-d "{\"allowlistIds\": [\"wl-12345","wl-12346"]}"
"$endpoint/config/systemsettings/allowlists/disable"

You provide the list of allowlists to disable through the body. Each allowlist is identified by its allowListId, which is an automatically generated ID that differs from the allowlist name. You can obtain this ID by running the config systemsettings:allowlists::get command.

config systemsettings:allowlists:acknowledge

The config systemsettings:allowlists:acknowledge command enables you to acknowledge the most recent enable or disable process. This command prevents you from mistakenly locking yourself out.

  • You must run this command between one and two minutes after every time that you run the config systemsettings:allowlists:enable::set or config systemsettings:allowlists:disable::set command. If you fail to acknowledge, the change reverts automatically.

  • The Acknowledge command is applied to only one enable or disable process, the most recently submitted command.

  • If you run the Acknowledge command too soon (less than a minute after the enable or disable command), you receive an error that advises you how many more seconds remain before you can successfully run the Acknowledge command.

  • CLI

  • REST

ctm config systemsettings:allowlists:acknowledge

The following example shows the REST API syntax for the config systemsettings:allowlists:acknowledge command in cURL:

Copy 
curl -H "x-api-key: $token" -X POST 
"$endpoint/config/systemsettings/allowlists/acknowledge"

config systemsettings:allowlists::get

The config systemsettings:allowlists::get command enables you to obtain a list of all defined allowlists, with details for each allowlist.

  • CLI

  • REST

ctm config systemsettings:allowlists::get

The following example shows the REST API syntax for the config systemsettings:allowlists::get command in cURL:

Copy 
curl -H "x-api-key: $token" -X GET 
"$endpoint/config/systemsettings/allowlists"

Response

The following example shows a config systemsettings:allowlists::get response with two defined allowlists.

Copy 
{
   "allowlists": [
      {
         "allowlistId": "wl-20251005-001",
         "allowlistName": "office-network",
         "ipType": "ipv4",
         "description": "The back office site in New York",
         "enabled":"True",
         "ipAddresses": [
            "206.0.113.0/22",
            "206.0.113.2/16"
         ]
      },
      {
         "allowlistId": "wl-20251005-002",
         "allowlistName": "vpn-network",
         "ipType": "ipv4",
         "enabled":"False",
         "ipAddresses": [
            "206.0.114.0/24"
         ]
      }
   ]
}

config systemsettings:allowlist::get

The config systemsettings:allowlist::get command enables you to obtain the details of a specific allowlist.

  • CLI

  • REST

ctm config systemsettings:allowlist::get <allowlistId>

The following example shows the REST API syntax for the config systemsettings:allowlist::get command in cURL:

Copy 
allowlistId="wl-12345"
curl -H "x-api-key: $token" -X GET 
"$endpoint/config/systemsettings/allowlist/$allowlistId"

where allowlistId uniquely identifies the allowlist. This ID is automatically generated, and it differs from the allowlist name. You can obtain it by running the config systemsettings:allowlists::get command.

config systemsettings:allowlist::update

The config systemsettings:allowlist::update command enables you to change the name, description, or list of IP addresses of a previously defined allowlist.

You cannot update an enabled (actively used) allowlist.

  • CLI

  • REST

ctm config systemsettings:allowlist::update <allowlistId> -f <configuration file>

The following example shows the REST API syntax for the config systemsettings:allowlist::update command in cURL:

Copy 
allowlistId="wl-12345"
curl -H "x-api-key: $token" -f "Allowlist5_changes.json"
-X PUT "$endpoint/config/systemsettings/allowlist/$allowlistId"

where

  • allowlistId uniquely identifies the allowlist. This ID is automatically generated, and it differs from the allowlist name. You can obtain it by running the config systemsettings:allowlists::get command.

  • configuration file defines a pathname to a JSON file that contains allowlist definitions to override the existing definitions, as shown in the following example:

    Copy 
    {
       "allowlistName": "office-network-updated",
       "description": "office allowlist description", 
       "ipAddresses": ["67.45.125.206/32", "67.40.120.201/32"]
    }

config systemsettings:allowlist::delete

The config systemsettings:allowlist::delete command enables you to delete a previously defined allowlist.

You cannot delete an enabled (actively used) allowlist.

  • CLI

  • REST

ctm config systemsettings:allowlist::delete <allowlistId>

The following example shows the REST API syntax for the config systemsettings:allowlist::delete command in cURL:

Copy 
allowlistId="wl-12345"
curl -H "x-api-key: $token" -X DELETE 
"$endpoint/config/systemsettings/allowlist/$allowlistId"

where allowlistId uniquely identifies the allowlist. This ID is automatically generated, and it differs from the allowlist name. You can obtain it by running the config systemsettings:allowlists::get command.