On This Page
Zones API
This API is an Early Access feature.
The Okta Zones API provides operations to manage Zones in your organization. There are two type of zones: Policy Network Zones and Block List Network Zones. Policy Network Zones may be used to guide policy decisions, and Block List Network Zones are used to deny access from certain IP addresses, locations, proxy types, or ASNs before policy evaluation.
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 |
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) |
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) |
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 about the expressions 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"
]
}
}
}
}