Network Zones

The Network Zones API provides operations to manage system default and custom zones in your Okta org. Network Zones are configurable boundaries that you can use to grant or restrict access to resources in your organization. They're used for two purposes:

POLICY: Network Zones used to guide policy decisions
BLOCKLIST: Network Zones used to deny access from certain IP addresses, locations, Autonomous System Numbers (ASNs), proxy types, or IP service categories before policy evaluation

Note: The Network Zone blocklist applies to all URLs for the org.

See Network zones in the Okta product documentation.

Your Okta org provides the following default system Network Zones that you can modify and use:

LegacyIpZone: The system default IP Network Zone
BlockedIpZone: The system default IP Blocklist Network Zone
DefaultEnhancedDynamicZone: The system default Enhanced Dynamic Network Zone

You can create and use the following custom Network Zones:

IP Network Zone (IP): Allows you to define network perimeters around a set of IPs
Dynamic Network Zone (DYNAMIC): Allows you to define network perimeters around location, IP type, or ASNs
Enhanced Dynamic Network Zone (DYNAMIC_V2): Extends the Dynamic Network Zone and allows you to include or exclude specific locations, ASNs, or IP service categories

Notes:

To create multiple Network Zones, you must have Adaptive MFA enabled in your Okta org.

Enhanced Dynamic Network Zones is a self-service Early Access (EA) feature. You must enable Enhanced Dynamic Network Zones in your Org settings to access this API. See Manage Early Access and Beta features.

List all Network Zones
OAuth 2.0: `okta.networkZones.read`

Lists all Network Zones with pagination. A subset of zones can be returned that match a supported filter expression or query.

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.

Okta supports filtering on the id, usage, and system properties. See Filter for more information on the expressions that are used in filtering.

Request

query Parameters

after	string Specifies the pagination cursor for the next page of Network Zones Example: after=BlockedIpZones
limit	integer <int32> Default: -1 Specifies the number of results for a page Example: limit=5
filter	string Filters zones by usage, ID, or system expression Example: filter=id eq "nzowc1U5Jh5xuAK0o0g3"

Responses

200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/zones

Request samples

Response samples

200
403
429

application/json

[{"type": "IP",
"id": "nzowc1U5Jh5xuAK0o0g3",
"name": "MyIpZone",
"status": "ACTIVE",
"usage": "POLICY",
"created": "2021-06-24T20:37:32.000Z",
"lastUpdated": "2021-06-24T20:37:32.000Z",
"system": false,
"gateways": [{"type": "CIDR",
"value": "1.2.3.4/24"
}
],
"proxies": [{"type": "RANGE",
"value": "3.3.4.5-3.3.4.15"
}
],
"_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"
]
}
}
}
}
]

Create a Network Zone
OAuth 2.0: `okta.networkZones.manage`

Creates a Network Zone

For an IP Network Zone, you must define either gateways or proxies.
For a Dynamic Network Zone, you must define at least one of the following: asns, locations, or proxyType.
For an Enhanced Dynamic Network Zone, you must define at least one of the following: asns, locations, or ipServiceCategories.

Request

Request Body schema: application/json
required

name

required

string <= 128 characters

Unique name for this Network Zone

type

required

string (NetworkZoneType)

The type of Network Zone

status

string (NetworkZoneStatus)

Network Zone status

Enum: "ACTIVE" "INACTIVE"

usage

string (NetworkZoneUsage)

The usage of the Network Zone

Enum: "BLOCKLIST" "POLICY"

Array of objects (NetworkZoneAddress)

The IP addresses (range or CIDR form) for an IP Network Zone. The maximum array length is 150 entries for admin-created IP zones, 1000 entries for IP blocklist zones, and 5000 entries for the default system IP Zone.

Array

type	string (NetworkZoneAddressType) Format of the IP addresses Enum: "CIDR" "RANGE"
value	string Value in CIDR/range form, depending on the `type` specified

Array of objects or null (NetworkZoneAddress)

The IP addresses (range or CIDR form) that are allowed to forward a request from gateway addresses for an IP Network Zone. These proxies are automatically trusted by Threat Insights and used to identify the client IP of a request. The maximum array length is 150 entries for admin-created zones and 5000 entries for the default system IP Zone.

Array

type	string (NetworkZoneAddressType) Format of the IP addresses Enum: "CIDR" "RANGE"
value	string Value in CIDR/range form, depending on the `type` specified

Responses

200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/zones

Request samples

application/json

{"type": "IP",
"name": "newNetworkZone",
"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"
}
]
}

Response samples

200
400
403
429

application/json

{"type": "IP",
"id": "nzowb8T5Jh5xuAJ0o0g7",
"name": "newNetworkZone",
"status": "ACTIVE",
"usage": "POLICY",
"created": "2021-08-09T21:32:01.000Z",
"lastUpdated": "2021-08-09T21:32:01.000Z",
"system": false,
"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/nzowb8T5Jh5xuAJ0o0g7",
"hints": {"allow": ["GET",
"PUT",
"DELETE"
]
}
},
"deactivate": {"href": "https://{yourOktaDomain}/api/v1/zones/nzowb8T5Jh5xuAJ0o0g7/lifecycle/deactivate",
"hints": {"allow": ["POST"
]
}
}
}
}

Retrieve a Network Zone
OAuth 2.0: `okta.networkZones.read`

Retrieves a Network Zone by zoneId

Request

path Parameters

zoneId

required

string

id of the Network Zone

Example: nzowc1U5Jh5xuAK0o0g3

Responses

200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/zones/{zoneId}

Request samples

Response samples

200
403
404
429

application/json

{"type": "IP",
"id": "nzowc1U5Jh5xuAK0o0g3",
"name": "MyIpZone",
"status": "ACTIVE",
"usage": "POLICY",
"created": "2021-06-24T20:37:32.000Z",
"lastUpdated": "2021-06-24T20:37:32.000Z",
"system": false,
"gateways": [{"type": "CIDR",
"value": "1.2.3.4/24"
}
],
"proxies": [{"type": "RANGE",
"value": "3.3.4.5-3.3.4.15"
}
],
"_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"
]
}
}
}
}

Replace a Network Zone
OAuth 2.0: `okta.networkZones.manage`

Replaces a Network Zone by zoneId. The replaced Network Zone type must be the same as the existing type. You can replace the usage (POLICY, BLOCKLIST) of a Network Zone by updating the usage attribute.

Request

path Parameters

zoneId

required

string

id of the Network Zone

Example: nzowc1U5Jh5xuAK0o0g3

Request Body schema: application/json
required

name

required

string <= 128 characters

Unique name for this Network Zone

type

required

string (NetworkZoneType)

The type of Network Zone

status

string (NetworkZoneStatus)

Network Zone status

Enum: "ACTIVE" "INACTIVE"

usage

string (NetworkZoneUsage)

The usage of the Network Zone

Enum: "BLOCKLIST" "POLICY"

Array of objects (NetworkZoneAddress)

The IP addresses (range or CIDR form) for an IP Network Zone. The maximum array length is 150 entries for admin-created IP zones, 1000 entries for IP blocklist zones, and 5000 entries for the default system IP Zone.

Array

type	string (NetworkZoneAddressType) Format of the IP addresses Enum: "CIDR" "RANGE"
value	string Value in CIDR/range form, depending on the `type` specified

Array of objects or null (NetworkZoneAddress)

The IP addresses (range or CIDR form) that are allowed to forward a request from gateway addresses for an IP Network Zone. These proxies are automatically trusted by Threat Insights and used to identify the client IP of a request. The maximum array length is 150 entries for admin-created zones and 5000 entries for the default system IP Zone.

Array

type	string (NetworkZoneAddressType) Format of the IP addresses Enum: "CIDR" "RANGE"
value	string Value in CIDR/range form, depending on the `type` specified

Responses

200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/zones/{zoneId}

Request samples

application/json

{"type": "IP",
"id": "nzovw2rFz2YoqmvwZ0g9",
"name": "UpdatedNetZone",
"status": "ACTIVE",
"system": false,
"usage": "POLICY",
"gateways": [{"type": "CIDR",
"value": "10.2.3.4/24"
},
{"type": "CIDR",
"value": "12.2.3.4/24"
},
{"type": "RANGE",
"value": "13.4.5.6-13.4.5.8"
},
{"type": "CIDR",
"value": "14.2.3.4/24"
}
],
"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/24-15.5.6.9"
}
],
"_links": {"self": {"href": "https://{yourOktaDomain}/api/v1/zones/nzovw2rFz2YoqmvwZ0g9",
"hints": {"allow": ["GET",
"PUT",
"DELETE"
]
}
},
"deactivate": {"href": "https://{yourOktaDomain}/api/v1/zones/nzovw2rFz2YoqmvwZ0g9/lifecycle/deactivate",
"hints": {"allow": ["POST"
]
}
}
}
}

Response samples

200
400
403
404
429

application/json

{"type": "IP",
"id": "nzovw2rFz2YoqmvwZ0g9",
"name": "UpdatedNetZone",
"status": "ACTIVE",
"usage": "POLICY",
"created": "2022-05-08T18:25:05.000Z",
"lastUpdated": "2022-05-10T13:15:22.000Z",
"system": false,
"gateways": [{"type": "CIDR",
"value": "10.2.3.4/24"
},
{"type": "CIDR",
"value": "12.2.3.4/24"
},
{"type": "RANGE",
"value": "13.4.5.6-13.4.5.8"
},
{"type": "CIDR",
"value": "14.2.3.4/24"
}
],
"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/24-15.5.6.9"
}
],
"_links": {"self": {"href": "https://{yourOktaDomain}/api/v1/zones/nzovw2rFz2YoqmvwZ0g9",
"hints": {"allow": ["GET",
"PUT",
"DELETE"
]
}
},
"deactivate": {"href": "https://{yourOktaDomain}/api/v1/zones/nzovw2rFz2YoqmvwZ0g9/lifecycle/deactivate",
"hints": {"allow": ["POST"
]
}
}
}
}

Delete a Network Zone
OAuth 2.0: `okta.networkZones.manage`

Deletes a Network Zone by zoneId

Notes:

You can't delete a Network Zone that's used by a Policy or Rule.

For Okta Identity Engine orgs, you can't delete a Network Zone with an ACTIVE status.

Request

path Parameters

zoneId

required

string

id of the Network Zone

Example: nzowc1U5Jh5xuAK0o0g3

Responses

204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/zones/{zoneId}

Request samples

Response samples

403
404
429

application/json

{"errorCode": "E0000006",
"errorSummary": "You do not have permission to perform the requested action",
"errorLink": "E0000006",
"errorId": "sampleNUSD_8fdkFd8fs8SDBK",
"errorCauses": [ ]
}

Activate a Network Zone
OAuth 2.0: `okta.networkZones.manage`

Activates a Network Zone by zoneId

Request

path Parameters

zoneId

required

string

id of the Network Zone

Example: nzowc1U5Jh5xuAK0o0g3

Responses

200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/zones/{zoneId}/lifecycle/activate

Request samples

Response samples

200
403
404
429

application/json

{"type": "IP",
"id": "nzowc1U5Jh5xuAK0o0g3",
"name": "MyIpZone",
"status": "ACTIVE",
"usage": "POLICY",
"created": "2021-06-24T20:37:32.000Z",
"lastUpdated": "2021-06-24T20:37:32.000Z",
"system": false,
"gateways": [{"type": "CIDR",
"value": "1.2.3.4/24"
}
],
"proxies": [{"type": "RANGE",
"value": "3.3.4.5-3.3.4.15"
}
],
"_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"
]
}
}
}
}

Deactivate a Network Zone
OAuth 2.0: `okta.networkZones.manage`

Deactivates a Network Zone by zoneId

Request

path Parameters

zoneId

required

string

id of the Network Zone

Example: nzowc1U5Jh5xuAK0o0g3

Responses

200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/zones/{zoneId}/lifecycle/deactivate

Request samples

Response samples

200
403
404
429

application/json

{"type": "IP",
"id": "nzowc1U5Jh5xuAK0o0g3",
"name": "MyIpZone",
"status": "INACTIVE",
"usage": "POLICY",
"created": "2021-06-24T20:37:32.000Z",
"lastUpdated": "2021-06-24T20:37:32.000Z",
"system": false,
"gateways": [{"type": "CIDR",
"value": "1.2.3.4/24"
}
],
"proxies": [{"type": "RANGE",
"value": "3.3.4.5-3.3.4.15"
}
],
"_links": {"self": {"href": "https://{yourOktaDomain}/api/v1/zones/nzowc1U5Jh5xuAK0o0g3",
"hints": {"allow": ["GET",
"PUT",
"DELETE"
]
}
},
"activate": {"href": "https://{yourOktaDomain}/api/v1/zones/nzowc1U5Jh5xuAK0o0g3/lifecycle/activate",
"hints": {"allow": ["POST"
]
}
}
}
}

Network Zones

List all Network ZonesOAuth 2.0: okta.networkZones.read

query Parameters

Create a Network ZoneOAuth 2.0: okta.networkZones.manage

Request Body schema: application/jsonrequired

Retrieve a Network ZoneOAuth 2.0: okta.networkZones.read

path Parameters

Replace a Network ZoneOAuth 2.0: okta.networkZones.manage

path Parameters

Request Body schema: application/jsonrequired

Delete a Network ZoneOAuth 2.0: okta.networkZones.manage

path Parameters

Activate a Network ZoneOAuth 2.0: okta.networkZones.manage

path Parameters

Deactivate a Network ZoneOAuth 2.0: okta.networkZones.manage

path Parameters

List all Network Zones
OAuth 2.0: `okta.networkZones.read`

Create a Network Zone
OAuth 2.0: `okta.networkZones.manage`

Request Body schema: application/json
required

Retrieve a Network Zone
OAuth 2.0: `okta.networkZones.read`

Replace a Network Zone
OAuth 2.0: `okta.networkZones.manage`

Request Body schema: application/json
required

Delete a Network Zone
OAuth 2.0: `okta.networkZones.manage`

Activate a Network Zone
OAuth 2.0: `okta.networkZones.manage`

Deactivate a Network Zone
OAuth 2.0: `okta.networkZones.manage`