On this page
Zones API
The Okta Zones API provides operations to manage Zones in your organization. There are two usage Zone types: Policy Network Zones and Blocklist Network Zones. Policy Network Zones are used to guide policy decisions. Blocklist 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 Blocklist 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 thatsystem=true
for theLegacyIpZone
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 |
|
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 |
|
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 |
Note: Continent codes are not intended to be used as
country
orregion
definitions. To include all of the countries in a continent, each country needs to be specified individually in a Location definition. If a continent code is used, then traffic from a designated country region within the continent might not be considered. For example, ifEU
orAP
is used instead of a country code, then the Location definition treats Europe or Asia/Pacific as generic codes for undesignated regions rather than inclusive of the countries they contain.
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"
]
}
}
}
}