Managing Locations Using API
Locations identify the various networks from which your organization sends its internet traffic. When an organization forwards its traffic to the Zscaler service through a GRE or IPSec tunnel, Zscaler provisions your organization's IP addresses, which you then add as locations. Sub-locations enable an organization to create new locations that reference IP addresses that are encapsulated within a GRE or IPSec tunnel, or that are passed to the Zscaler service through X-Forwarded-For (XFF) headers. You can add locations and sub-locations using the Cloud Service API or the ZIA Admin Portal. To learn more about the API endpoints used for these configurations, see API Reference.
If your locations and sub-locations are managed by a Software-Defined Wide Area Networking (SD-WAN) partner, see SD-WAN API Integration for IPSec VPN Tunnel Provisioning. The following information only provides details on how to use Location Management resources to set up locations and sub-locations if they are not managed by an SD-WAN partner.
Getting a List of Locations and Sub-Locations
Location Management resources allow you to export all attributes of a Zscaler service-defined location as a request. Calling GET /locations retrieves a list of location objects managed by you. For example, in Python, a GET request would appear as follows:
conn.request("GET", "/api/v1/locations", headers=headers)
So the response would be:
[
{
"name": "nyc-2",
"id": 4562809,
"managedBy": {
"id": 1,
"name": "Self"
},
"vpnCredentials": [
{
"id": 4562807,
"type": "UFQDN",
"fqdn": "nyc-1-37@yourcompany.com",
"comments": "created automatically"
}
]
},
{
"name": "sjc-1",
"id": 4562808,
"managedBy": {
"id": 1,
"name": "Self"
},
"vpnCredentials": [
{
"id": 4562805,
"type": "UFQDN",
"fqdn": "sjc-1-37@yourcompany.com",
"comments": "created automatically"
}
]
}
]
If you have locations and sub-locations that you manage and others that an SD-WAN partner manages, then calling GET /locations retrieves a list of location objects managed by you (i.e., Self) and your specified SD-WAN partner. However, SD-WAN partners cannot retrieve objects that are managed by you (i.e., Self). To learn more, see the Understanding the managedBy Attribute.
Calling GET /locations/{locationId}/sublocations retrieves a list of sub-location objects for the specified locationId. For example, in Python, a GET request would appear as follows:
conn.request("GET ", "/api/v1/locations/6793981/sublocations", headers=headers)
So the response would be:
[
{
"id": 6793982,
"name": "guest-wifi",
"parentId": 6793981,
"ipAddresses": ["10.131.2.128-10.131.3.255"],
"surrogateRefreshTimeInMinutes": 0
},
{
"id": 6793983,
"name": "other",
"parentId": 6793981,
"otherSubLocation": true,
"surrogateRefreshTimeInMinutes": 0
}
]
If used, Zscaler recommends changing the pageSize query parameter to more than 100, or iterating through all results using the page query parameter, until the last page has less than 100 results.
Adding Locations and Sub-Locations
To add a location with VPN credentials or a static IP address, make sure that the following prerequisites are met:
- If you want to add a location with VPN credentials, you need the ID and other details of the VPN credentials. You can retrieve the list of VPN credentials available for associating with a location by sending a GET request to
/vpnCredentialswith theincludeOnlyWithoutLocationquery parameter set totrue. If the VPN credentials don't already exist, you need to add them by sending a POST request to/vpnCredentials. - If you want to add a location with a static IP address, ensure that you have a self-provisioned static IP address or one that has been provisioned for your organization by Zscaler.
To add a location:
- Send a POST request to
/locationsand use the following key-value pairs in the Body:name: A string (e.g., "nyc-4").vpnCredentials: If you are adding a location with VPN credentials, then this parameter and its key-value pairs are required in the request:id: Specify the VPN ID as an integer (e.g., "4562873").type: Specify the authentication type as a string (e.g., "UFQDN").fqdn: This parameter is only required if you are using theUFQDNorXAUTHauthentication type. Specify the fully qualified domain name as a string (e.g., "nyc-1-38@yourcompany.com").
To learn more, see Configuring VPN Credentials for IPSec Tunnels Using API.
ipAddresses: If you are adding a location with a static IP address, then this parameter is required in the request (e.g., ["50.60.70.80"]).
To add a sub-location:
- Send a POST request to
/locationsand use the following key-value pairs in the Body:parentId: The parent location's ID. A string (e.g., "6793981").name: A string (e.g., "guest-wifi").ipAddresses: The IP address for the sub-location. You can also specify IP addresses in a range (e.g., ["10.131.2.128-10.131.3.255"]).
- Activate the changes to your configuration.
Updating Locations and Sub-Locations
To update a location or sub-location based on a specified location ID:
- Get information for a specific location by sending a GET request to
/locations/{locationId}or/locations/{locationId}/sublocations.
If you send a GET request to /locations, the pre-shared key (PSK) for the associated VPN credential is not included in the response for security reasons.
- Modify the location or sub-location's information by sending a PUT request to
/locations/{locationId}, and including all of the required key-value pairs in the Body.
You cannot update a location or sub-location's fully qualified domain name (fqdn) by sending a PUT request to /locations/{locationId}. If the fqdn is modified in the request, the change is ignored.
Deleting Locations and Sub-Locations
If you delete a location, then any sub-locations associated to it are also deleted.
To delete a location or sub-location based on a specified location ID:
- Send a DELETE request to
/locations/{locationId}.
You can also bulk delete locations, up to a maximum of 100 locations per request, by calling DELETE /locations/bulkDelete.