Skip to main content

REST APIs for 23.2

IP Lists

This PubIic Stable API can get, create, update, and delete IP lists.

IP lists can be used in rules to define sets of trusted IP address, IP address ranges, or CIDR blocks allowed into your datacenter that are allowed to access workloads in your network.

IP Lists API

Functionality

HTTP

URI

Get a collection of IP lists

GET

[api_version][org_href]/sec_policy/draft/ip_lists

Get an individual IP list

GET

[api_version][ip_list_href]

Create an IP list

POST

[api_version][org_href]/sec_policy/draft/ip_lists

Update an IP list

PUT

[api_version][ip_list_href]

Delete an IP list

DELETE

[api_version][ip_list_href]

Active vs Draft

This API operates on provisionable objects, which exist in either a draft (not provisioned) state or an active (provisioned) state.

Provisionable items include label groups, services, rulesets, IP lists, virtual services, firewall settings, enforcement boundaries, and virtual servers. For these objects, the URL of the API call must include the element called :pversion, which can be set to either draft or active.

Depending on the method, the API follows these rules:

  • For GET operations — :pversion can be draft, active, or the ID of the security policy.

  • For POST, PUT, DELETE — :pversion can be draft (you cannot operate on active items) or the ID if the security policy.

Get IP Lists

This API allows you to get a collection of IP lists or a single IP list from an organization.

By default, the maximum number returned on a GET collection of IP lists is 500. If you want to get more than 500 IP lists, use an Asynchronous GET Collection.

URI to Get Collection of IP Lists

GET [api_version][org_href]/sec_policy/draft/ip_lists

URI to Get an Individual IP List

GET [api_version][ip_list_href]
Query Parameters

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

pversion

Security Policy Version

String

Yes

description

Description of IP list(s) to return. Supports partial matches

String

No

external_data_set

The data source from which the resource originates.

For example, if this workload information is stored in an external database.

String

No

external_data_reference

A unique identifier within the external data source.

For example, if this workload information is stored in an external database.

String

No

ip_address

IP address matching the IP lists to return. Supports partial matches.

String

No

fqdn

IP lists matching FQDN. Supports partial matches

String

No

max_results

The maximum number of results you want to return when using the

GET method. The maximum limit for returned IP lists is 500.

Integer

No

name

Name of IP list(s) to return. Supports partial matches

String

No

ip_list_id

IP list ID (for [api_version][ip_list_href]

String

Yes

Properties

Property

Description

Type

Required

href

URI of the ip list

String

Yes

name

Name of the IP lists to return, which has to be unique..

String

Yes

description

Description of IP list(s) to return. Supports partial matches

String

No

external_data_set

The data source from which the resource originates.

For example, if this workload information is stored in an external database.

String,

Null

No

external_data_reference

A unique identifier within the external data source.

For example, if this workload information is stored in an external database.

String,

Null

No

fqdns

Collection of FQDNs.

Array.

Required:

fqdn

No

ip_list_id

IP list ID (for [api_version][ip_list_href]

String

Yes

Curl Command to Get Collection of IP Lists

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/ip_lists -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

{
     {
        href: "/orgs/2/sec_policy/draft/ip_lists/309"
        id: 309
        created_at: "2020-04-17T21:59:44Z"
        updated_at: "2020-04-17T21:59:44Z"
        deleted_at: null
        created_by: {
            href: "/users/76"
     }
        updated_by: {
            href: "/users/76"
     }
        deleted_by: null
        name: "Good IPs 2"
        description: null
        ip_ranges: [
            {
               description: "My good IPs for web app"
               from_ip: "192.0.2.0"
               to_ip: null
            }
         ]
}

Curl Command to Get an IP List

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/ip_lists/312 -H "Accept: application/json" -u $KEY:$TOKEN
Create an IP List

This API allows you to create IP lists (allowlists) so they can be used for creating rules in rulesets. An IP list can contain a single IP address or an IP address range.

Note

Denylist IP lists are not supported in this release.

Warning

Please be aware of the following:

Warning

0.0.0.0/0 means 0-255 . 0-255 . 0-255 . 0-255 or all possible IP addresses.

Warning

0.0.0.0 without the trailing "/0", means a single IP (not ANY IP). This is a very rare but sometimes needed object, specifically for things like DHCP Discovery.

Warning

0.0.0.0 when used improperly might trigger an error, prevent the list from being accepted, and consequently block traffic.

Warning

Use the correct syntax for the intended purpose.

URI to Create an IP List

POST [api_version][org_href]/sec_policy/draft/ip_lists

Request Properties

Example JSON request body for a single IP list:

{
     "name": "Good IPs",
     "ip_ranges": [
           {
               "description": "Good IPs allowed to access app server",
               "from_ip": "192.0.2.0"
           }
     ]
}

Curl Command to Create IP List

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/ip_lists -H "Accept: application/json" -u $KEY:$TOKEN -d '{"name": "Good IPs", "ip_ranges":[{"description": "Good IPs allowed to access app server", "from_ip": "192.0.2.0"}]}'

Response Body

{
     href: "/orgs/2/sec_policy/draft/ip_lists/316"
     created_at: "2020-04-18T00:19:55Z"
     updated_at: "2020-04-18T00:19:55Z"
     deleted_at: null
     created_by: {
          href: "/users/11"
     }
     updated_by: {
          href: "/users/11"
     }
     deleted_by: null
     name: "Good  IPs"
     description: null
     ip_ranges: [
         {
             description: "Good IPs"
             from_ip: "192.0.2.0"
             to_ip: null
         }
     ]
}
Update an IP List

This API updates a specific IP list identified by its HREF. Get a collection of IP lists to find IP list HREFs .

Example IP list HREF:

/orgs/2/sec_policy/draft/ip_lists/316

URI to Update an IP List

PUT [api_version][ip_list_href]

Example Request Body to Update an IP List

{
     "name": "Better IPs",
     "list_type": "allow",
     "ip_ranges": [
         {
             "description": "More allowed IPs for web app",
             "from_ip" : "192.0.2.0"
             "to_ip" : "24"
         }
     ]
}

Curl Command to Update IP List

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/ip_lists/312 -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{ "name": "Better IPs", "list_type": "allow", "ip_ranges": [{"description": "Better IPs for web app", "from_ip": "192.0.2.0", "to_ip": "24"}]}'
Delete an IP List

This API removes an IP list from a organization:

URI to Delete an API List

DELETE [api_version][ip_list_href]

Curl Command to Delete IP List

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/ip_lists/316 -u $KEY:$TOKEN
See also: