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:

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 
application/json
[]
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"  
useAsExemptList
boolean
You can only use this parameter when making a request to the Replace the network zone endpoint (/api/v1/zones/{zoneId}).
Set this parameter to true in your request when you update the DefaultExemptIpZone to allow IPs through the blocklist.


 
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": [
    • {
      },
    • {
      }
    ],
  • "proxies": [
    • {
      },
    • {
      }
    ]
}
Response samples 
application/json
{}
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 
application/json
{}
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.


IP exempt zone

If you have the IP exempt zone feature enabled, you can allow traffic from specific gateway IPs irrespective of Okta ThreatInsight configurations, blocked network zones, or IP change events within Identity Threat Protection with Okta AI.



When you enable this feature, Okta creates a zone called DefaultExemptIpZone. Gateway IPs that you add to this zone always have access to Okta resources. See IP exempt zone.




Note: You can't add trusted proxy IPs to this zone, delete the zone, or create additional exempt IP zones.




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"  
useAsExemptList
boolean
You can only use this parameter when making a request to the Replace the network zone endpoint (/api/v1/zones/{zoneId}).
Set this parameter to true in your request when you update the DefaultExemptIpZone to allow IPs through the blocklist.


 
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": [
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "proxies": [
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "_links": {}
}
Response samples 
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": [
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "proxies": [
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "_links": {}
}
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 
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 
application/json
{}
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 
application/json
{}