Zones API

This API is an Early Access feature.

The Okta Zones API provides operations to manage Zones in your organization. There are two usage Zone types: Policy Network Zones and Block List Network Zones. Policy Network Zones are used to guide policy decisions. Block List Network Zones are used to deny access from certain IP addresses, locations, proxy types, or Autonomous System Numbers (ASNs) before policy evaluation.

A default system Policy Network Zone is provided in your Okta org. You can use the Zones API to modify the default Policy Network Zone or to create a custom Policy or Block List Network Zone. When you create your custom Zone, you can specify if the Zone is an IP Zone or a Dynamic Zone. An IP Zone allows you to define network perimeters around a set of IPs, whereas a Dynamic Zone allows you to define network perimeters around location, IP type, and ASNs.

Zone object

Base Network Zone properties

The following attributes are shared by all Network Zone objects:

Field Name	Description	Data Type	Required	Max Length
type	Type of Zone: `IP`, `DYNAMIC`	String	Yes	N/A
id	Unique identifier for this Zone	String	No (Assigned)	N/A
name	Unique name for this Zone	String	Yes	128 (chars)
system	Indicates if this is a system Network Zone. For admin-created Zones, this is always `false`.	boolean	No (Assigned)	N/A
usage	Usage of Zone: `POLICY`, `BLOCKLIST`	String	No	N/A

Note: The system IP Policy Network Zone (LegacyIpZone) is included by default in your Okta org. Notice that system=true for the LegacyIpZone object. Admin users can modify the name of this default system Zone and can add up to 5000 gateway or proxy IP entries.

IP Zone properties

One of the following attributes must be defined. These attributes are defined by IP Zone objects:

Field Name	Description	Data Type	Required	Max Length
gateways	IP addresses (range or CIDR form) of this Zone	Array of Address Objects	No	150 (entries for admin-created IP Zones) 1000 (entries for IP Block List Zones) 5000 (entries for the default system IP Zone)
proxies	IP addresses (range or CIDR form) that are allowed to forward a request from gateway addresses. These proxies are automatically trusted by Threat Insights. These proxies are used to identify the client IP of a request.	Array of Address Objects	No	150 (entries for admin-created IP Zones) 5000 (entries for the default system IP Zone)

Address object

Each Address object specifies a set of IP addresses that are expressed using either range or CIDR form.

Field Name	Description	Data Type	Required
type	Format of the value: `CIDR`, `RANGE`	String	Yes
value	Value in CIDR/range form depending on the type specified	String	Yes

Address object example (CIDR)

{
    "type": "CIDR",
    "value": "1.2.3.4/24"
  }

Address object example (range)

{
    "type": "RANGE",
    "value": "1.2.3.0-1.2.3.255"
  }

IP Zone example

{
  "type": "IP",
  "id": "nzouagptWUz5DlLfM0g3",
  "name": "newNetworkZone",
  "status": "ACTIVE",
  "created": "2017-01-24T19:52:34.000Z",
  "lastUpdated": "2017-01-24T19:52:34.000Z",
  "system": false,
  "gateways": [
    {
      "type": "CIDR",
      "value": "1.2.3.4/24"
    },
    {
      "type": "RANGE",
      "value": "2.3.4.5-2.3.4.15"
    }
  ],
  "proxies": [
    {
      "type": "CIDR",
      "value": "2.2.3.4/24"
    },
    {
      "type": "RANGE",
      "value": "3.3.4.5-3.3.4.15"
    }
  ]
}

Dynamic Zone properties

One of the following attributes must be defined. These attributes are defined by Dynamic Zone objects:

Field Name	Description	Data Type	Required	Max Length
proxyType	One of: `""` or `null` (when not specified), `Any` (meaning any proxy), `Tor`, `NotTorAnonymizer`	String	No	N/A
locations	The geolocations of this Zone	Array of Location objects	No	75 (entries)
asns	Format of each array value: a string representation of an ASN numeric value	Array of Strings	No	75 (entries)

Location object

Each Location object specifies an ISO-3166-1 (opens new window) country code and an optional ISO-3166-2 (opens new window) region code.

Field Name	Description	Data Type	Required
country	Format of the value: length 2 ISO-3166-1 country code	String	Yes
region	Format of the value: `countryCode`-`regionCode`, or `null` if empty	String	No

Location object example (with region)

{
    "country": "AF",
    "region": "AF-BGL"
  }

Location object example (without region)

{
    "country": "AF",
    "region": null
  }

Dynamic Zone example

{
    "type": "DYNAMIC",
    "id": "nzowc1U5Jh5xuAK0o0g3",
    "name": "test",
    "status": "ACTIVE",
    "created": "2019-05-17T18:44:31.000Z",
    "lastUpdated": "2019-05-21T13:50:49.000Z",
    "system": false,
    "locations": [{
        "country": "AX",
        "region": null
    },
    {
        "country": "AF",
        "region": "AF-BGL"
    }],
    "proxyType": "Any",
    "asns": ["23457"]
}

Zone API operations

Create a Policy Network Zone

POST /api/v1/zones

Creates a new Policy Network Zone

Valid request example

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "IP",
  "id": null,
  "name": "newNetworkZone",
  "status": "ACTIVE",
  "created": null,
  "lastUpdated": null,
  "gateways": [
    {
      "type": "CIDR",
      "value": "1.2.3.4/24"
    },
    {
      "type": "CIDR",
      "value": "2.3.4.5/24"
    }
  ],
  "proxies": [
    {
      "type": "CIDR",
      "value": "2.2.3.4/24"
    },
    {
      "type": "CIDR",
      "value": "3.3.4.5/24"
    }
  ]
}' "https://${yourOktaDomain}/api/v1/zones"

Successful response example

{
  "type": "IP",
  "id": "nzouagptWUz5DlLfM0g3",
  "name": "newNetworkZone",
  "status": "ACTIVE",
  "usage": "POLICY",
  "created": "2017-01-24T19:52:34.000Z",
  "lastUpdated": "2017-01-24T19:52:34.000Z",
  "gateways": [
    {
      "type": "CIDR",
      "value": "1.2.3.4/24"
    },
    {
      "type": "CIDR",
      "value": "2.3.4.5/24"
    }
  ],
  "proxies": [
    {
      "type": "CIDR",
      "value": "2.2.3.4/24"
    },
    {
      "type": "CIDR",
      "value": "3.3.4.5/24"
    }
  ],
  "_links": {
    "self": {
      "href": "https://${yourOktaDomain}/api/v1/zones/nzouagptWUz5DlLfM0g3",
      "hints": {
        "allow": [
          "GET",
          "PUT",
          "DELETE"
        ]
      }
    },
    "deactivate": {
      "href": "https://${yourOktaDomain}/api/v1/zones/nzouagptWUz5DlLfM0g3/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Invalid request example

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "IP",
  "id": null,
  "name": "Zone with Invalid IP Range",
  "status": "ACTIVE",
  "created": null,
  "lastUpdated": null,
  "system": false,
  "gateways": [
    {
      "type": "RANGE",
      "value": "1.2.3.4.5-1.2.3.6"
    }
  ],
  "proxies": [
    {
      "type": "CIDR",
      "value": "2.2.3.4/24"
    }
  ]
}' "https://${yourOktaDomain}/api/v1/zones"

Unsuccessful response example

{
    "errorCode": "E0000001",
    "errorSummary": "Api validation failed: gateways",
    "errorLink": "E0000001",
    "errorId": "oae_LwW8xNqTqCzUpBh-plasQ",
    "errorCauses": [
        {
            "errorSummary": "gateways: The IP: 1.2.3.4.5 in the RANGE: 1.2.3.4.5-1.2.3.6 is invalid. Make sure it is a valid IPV4."
        }
    ]
}

Create a Block List Network Zone

POST /api/v1/zones

Creates a new Block List Network Zone

Request example

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "IP",
  "id": null,
  "name": "newBlockListNetworkZone",
  "status": "ACTIVE",
  "usage": "BLOCKLIST",
  "created": null,
  "lastUpdated": null,
  "gateways": [
    {
      "type": "CIDR",
      "value": "1.2.3.4/24"
    },
    {
      "type": "CIDR",
      "value": "2.3.4.5/24"
    }
  ],
  "proxies": null
}' "https://${yourOktaDomain}/api/v1/zones"

Response example

{
    "type": "IP",
    "id": "nzo1qasnPb1kqEq0e0g4",
    "name": "newBlockListNetworkZone",
    "status": "ACTIVE",
    "usage": "BLOCKLIST",
    "created": "2020-10-12T18:58:02.000Z",
    "lastUpdated": "2020-10-12T18:58:02.000Z",
    "system": false,
    "gateways": [
        {
            "type": "CIDR",
            "value": "1.2.3.4/24"
        },
        {
            "type": "CIDR",
            "value": "2.3.4.5/24"
        }
    ],
    "proxies": null,
    "_links": {
        "self": {
            "href": "http://rain.okta1.com:1802/api/v1/zones/nzo1qasnPb1kqEq0e0g4",
            "hints": {
                "allow": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        },
        "deactivate": {
            "href": "http://rain.okta1.com:1802/api/v1/zones/nzo1qasnPb1kqEq0e0g4/lifecycle/deactivate",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Get a Network Zone

GET /api/v1/zones/${zoneId}

Gets a Network Zone by ID

Request parameters

The Zone ID described in the Zone object is required.

Request example

curl -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/zones/nzowc1U5Jh5xuAK0o0g3"

Response example

{
    "type": "DYNAMIC",
    "id": "nzowc1U5Jh5xuAK0o0g3",
    "name": "test",
    "status": "ACTIVE",
    "usage": "POLICY",
    "created": "2019-05-17T18:44:31.000Z",
    "lastUpdated": "2019-05-21T13:50:49.000Z",
    "system": false,
    "locations": [{
        "country": "AX",
        "region": null
    }],
    "proxyType": null,
    "asns": ["23457"],
    "_links": {
        "self": {
            "href": "https://${yourOktaDomain}/api/v1/zones/nzowc1U5Jh5xuAK0o0g3",
            "hints": {
                "allow": ["GET", "PUT", "DELETE"]
            }
        },
        "deactivate": {
            "href": "https://${yourOktaDomain}/api/v1/zones/nzowc1U5Jh5xuAK0o0g3/lifecycle/deactivate",
            "hints": {
                "allow": ["POST"]
            }
        }
    }
}

List Zones

GET /api/v1/zones

Lists all zones

A subset of Zones can be returned that match a supported filter expression or query criteria.

Request parameters

List all Zones (no parameters)
List Zones with a filter (filter)

Parameter	Description	Param Type	DataType	Required
filter	Filter Zones with a supported expression for the `id` and `usage` properties	Query	String	No
limit	Specifies the number of results returned	Query	Integer	No

Response parameters

Array of Zones

List all Zones

Returns a list of all zones

Request example

curl -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/zones"

Response example

[
    {
        "id": "nzoo6s03dLsg2I7HK0g3",
        "name": "BlockedIpZone",
        "type": "IP",
        "status": "ACTIVE",
	"usage": "BLOCKLIST",
        "created": "2017-07-28T23:24:36.000Z",
        "lastUpdated": "2017-08-14T20:41:08.000Z",
        "system": true,
        "gateways": [
            {
                "type": "RANGE",
                "value": "123.123.123.123-123.123.123.123"
            }
        ],
        "proxies": null,
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/zones/nzoo6s03dLsg2I7HK0g3",
                "hints": {
                    "allow": [
                        "GET",
                        "PUT",
                        "DELETE"
                    ]
                }
            },
            "deactivate": {
                "href": "https://${yourOktaDomain}/api/v1/zones/nzoo6s03dLsg2I7HK0g3/lifecycle/deactivate",
                "hints": {
                    "allow": [
                        "POST"
                    ]
                }
            }
        }
    },
   {
        "id": "nzowc1U5Jh5xuAK0o0g3",
        "type": "DYNAMIC",
        "name": "test",
        "status": "ACTIVE",
	"usage": "POLICY",
        "created": "2019-05-17T18:44:31.000Z",
        "lastUpdated": "2019-05-21T13:50:49.000Z",
        "system": false,
        "locations": [{
            "country": "AX",
            "region": null
        }],
        "proxyType": null,
        "asns": ["23457"],
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/zones/nzowc1U5Jh5xuAK0o0g3",
                "hints": {
                    "allow": ["GET", "PUT", "DELETE"]
                }
            },
            "deactivate": {
                "href": "https://${yourOktaDomain}/api/v1/zones/nzowc1U5Jh5xuAK0o0g3/lifecycle/deactivate",
                "hints": {
                    "allow": ["POST"]
                }
            }
        }
    },
    {
        "id": "nzowduJMXKsPkRqL40g3",
        "name": "AiurIpZone",
        "type": "IP",
        "status": "ACTIVE",
	"usage": "POLICY",
        "created": "2017-08-14T20:08:15.000Z",
        "lastUpdated": "2017-08-14T20:08:15.000Z",
        "system": false,
        "gateways": [
            {
                "type": "RANGE",
                "value": "127.0.0.1-127.0.0.1"
            }
        ],
        "proxies": null,
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/zones/nzowduJMXKsPkRqL40g3",
                "hints": {
                    "allow": [
                        "GET",
                        "PUT",
                        "DELETE"
                    ]
                }
            },
            "deactivate": {
                "href": "https://${yourOktaDomain}/api/v1/zones/nzowduJMXKsPkRqL40g3/lifecycle/deactivate",
                "hints": {
                    "allow": [
                        "POST"
                    ]
                }
            }
        }
    }
]

List Zones with a filter

Lists all Zones that match the filter criteria

This operation requires URL encoding. For example, filter=(id eq "nzoul0wf9jyb8xwZm0g3" or id eq "nzoul1MxmGN18NDQT0g3") is encoded as filter=%28id+eq+%22nzoul0wf9jyb8xwZm0g3%22+or+id+eq+%22nzoul1MxmGN18NDQT0g3%22%29.

We support filtering on the id and usage properties. See Filtering for more information on the expressions that are used in filtering.

Request example

curl -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/zones?limit=100&filter=%28%28id+eq+%22nzoul0wf9jyb8xwZm0g3%22+or+id+eq+%22nzoul1MxmGN18NDQT0g3%22%29+and+usage+eq+%22POLICY%22%29"

Response example

[
  {
    "id": "nzoul0wf9jyb8xwZm0g3",
    "name": "0",
    "type": "IP",
    "status": "ACTIVE",
    "usage": "POLICY",
    "created": "2017-01-24T19:52:48.000Z",
    "lastUpdated": "2017-01-24T19:52:48.000Z",
    "system": false,
    "gateways": [
      {
        "type": "CIDR",
        "value": "1.2.3.4/24"
      },
      {
        "type": "CIDR",
        "value": "2.3.4.5/24"
      },
      {
        "type": "RANGE",
        "value": "3.4.5.6-3.4.5.8"
      },
      {
        "type": "RANGE",
        "value": "4.5.6.7-4.5.6.9"
      }
    ],
    "proxies": [
      {
        "type": "CIDR",
        "value": "2.2.3.4/24"
      },
      {
        "type": "CIDR",
        "value": "3.3.4.5/24"
      },
      {
        "type": "RANGE",
        "value": "4.4.5.6-4.4.5.8"
      },
      {
        "type": "RANGE",
        "value": "5.5.6.7-5.5.6.9"
      }
    ],
    "_links": {
      "self": {
        "href": "https://${yourOktaDomain}/api/v1/zones/nzoul0wf9jyb8xwZm0g3",
        "hints": {
          "allow": [
            "GET",
            "PUT",
            "DELETE"
          ]
        }
      },
      "deactivate": {
        "href": "https://${yourOktaDomain}/api/v1/zones/nzoul0wf9jyb8xwZm0g3/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "id": "nzoul1MxmGN18NDQT0g3",
    "name": "1",
    "type": "IP",
    "status": "ACTIVE",
    "usage": "POLICY",
    "created": "2017-01-24T19:52:48.000Z",
    "lastUpdated": "2017-01-24T19:52:48.000Z",
    "system": false,
    "gateways": [
      {
        "type": "CIDR",
        "value": "1.2.3.4/24"
      },
      {
        "type": "CIDR",
        "value": "2.3.4.5/24"
      },
      {
        "type": "RANGE",
        "value": "3.4.5.6-3.4.5.8"
      },
      {
        "type": "RANGE",
        "value": "4.5.6.7-4.5.6.9"
      }
    ],
    "proxies": [
      {
        "type": "CIDR",
        "value": "2.2.3.4/24"
      },
      {
        "type": "CIDR",
        "value": "3.3.4.5/24"
      },
      {
        "type": "RANGE",
        "value": "4.4.5.6-4.4.5.8"
      },
      {
        "type": "RANGE",
        "value": "5.5.6.7-5.5.6.9"
      }
    ],
    "_links": {
      "self": {
        "href": "https://${yourOktaDomain}/api/v1/zones/nzoul1MxmGN18NDQT0g3",
        "hints": {
          "allow": [
            "GET",
            "PUT",
            "DELETE"
          ]
        }
      },
      "deactivate": {
        "href": "https://${yourOktaDomain}/api/v1/zones/nzoul1MxmGN18NDQT0g3/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  }
 ]

Update a Network Zone

PUT /api/v1/zones/${zoneId}

Updates an existing Network Zone

Request parameters

A valid Zone object with the ID of the Network Zone to update is required.

The updated Network Zone type must be the same as the existing type.

You may update the usage (POLICY, BLOCKLIST) of a Network Zone by updating the usage attribute.

Request example

curl -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "IP",
  "id": "nzovw2rFz2YoqmvwZ0g3",
  "name": "UpdatedNetZone",
  "status": "ACTIVE",
  "usage": "POLICY",
  "created": "2017-01-24T19:53:28.000Z",
  "lastUpdated": "2017-01-24T19:53:28.000Z",
  "gateways": [
    {
      "type": "CIDR",
      "value": "10.2.3.4/24"
    },
    {
      "type": "CIDR",
      "value": "12.3.4.5/24"
    },
    {
      "type": "RANGE",
      "value": "13.4.5.6-13.4.5.8"
    },
    {
      "type": "RANGE",
      "value": "14.5.6.7-14.5.6.9"
    }
  ],
  "proxies": [
    {
      "type": "CIDR",
      "value": "12.2.3.4/24"
    },
    {
      "type": "CIDR",
      "value": "13.3.4.5/24"
    },
    {
      "type": "RANGE",
      "value": "14.4.5.6-14.4.5.8"
    },
    {
      "type": "RANGE",
      "value": "15.5.6.7-15.5.6.9"
    }
  ]
}' "https://${yourOktaDomain}/api/v1/zones/nzovw2rFz2YoqmvwZ0g3"

Response example

{
  "type": "IP",
  "id": "nzovw2rFz2YoqmvwZ0g3",
  "name": "UpdatedNetZone",
  "status": "ACTIVE",
  "usage": "POLICY",
  "created": "2017-01-24T19:53:28.000Z",
  "lastUpdated": "2017-01-24T19:53:28.000Z",
  "system": false,
  "gateways": [
    {
      "type": "CIDR",
      "value": "10.2.3.4/24"
    },
    {
      "type": "CIDR",
      "value": "12.3.4.5/24"
    },
    {
      "type": "RANGE",
      "value": "13.4.5.6-13.4.5.8"
    },
    {
      "type": "RANGE",
      "value": "14.5.6.7-14.5.6.9"
    }
  ],
  "proxies": [
    {
      "type": "CIDR",
      "value": "12.2.3.4/24"
    },
    {
      "type": "CIDR",
      "value": "13.3.4.5/24"
    },
    {
      "type": "RANGE",
      "value": "14.4.5.6-14.4.5.8"
    },
    {
      "type": "RANGE",
      "value": "15.5.6.7-15.5.6.9"
    }
  ],
  "_links": {
    "self": {
      "href": "https://${yourOktaDomain}/api/v1/zones/nzovw2rFz2YoqmvwZ0g3",
      "hints": {
        "allow": [
          "GET",
          "PUT",
          "DELETE"
        ]
      }
    },
    "deactivate": {
      "href": "https://${yourOktaDomain}/api/v1/zones/nzovw2rFz2YoqmvwZ0g3/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Edit This Page On GitHub

On This Page

Zones API

Zone object

Base Network Zone properties

IP Zone properties

Address object

Address object example (CIDR)

Address object example (range)

IP Zone example

Dynamic Zone properties

Location object

Location object example (with region)

Location object example (without region)

Dynamic Zone example

Zone API operations

Create a Policy Network Zone

Valid request example

Successful response example

Invalid request example

Unsuccessful response example

Create a Block List Network Zone

Request example

Response example

Get a Network Zone

Request parameters

Request example

Response example

List Zones

Request parameters

Response parameters

List all Zones

Request example

Response example

List Zones with a filter

Request example

Response example

Update a Network Zone

Request parameters

Request example

Response example