Migration guide from Beta to API v1.0
Overview
This guide outlines the key differences between the Beta and v1.0.0 versions of the API, including changes to endpoints, parameter modifications, rate limits, and new features.
Base Path Changes
Beta:
The API base path was
/api/beta/.All endpoints included this prefix.
Example:
/api/beta/access-groups
v1.0.0:
The base path is now
/api/v1/.Example:
/api/v1/access-groups
Endpoint Grouping
Beta:
Resources were separate groups with individual endpoints:
IP Services:
/api/beta/ip-servicesApplications:
/api/beta/applicationsConnectors:
/api/beta/connectors
v1.0.0:
Resources are grouped under Networks and Hosts:
IP Services:
/api/v1/networks/ip-servicesApplications:
/api/v1/networks/applicationsConnectors:
/api/v1/networks/connectors
Introduction of IPsec
New Feature: IPsec support was introduced for connectors under networks.
Endpoints for managing IPsec tunnels:
/api/v1/networks/connectors/{id}/ipsec/start/api/v1/networks/connectors/{id}/ipsec/stop
Settings Endpoints
New settings endpoints introduced for fine-grained control:
/api/v1/settings/auth/ldap/group-mappings
/api/v1/settings/auth/saml/group-mappings
/api/v1/settings/auth/trusted-devices-allowed
/api/v1/settings/auth/two-factor-auth
/api/v1/settings/dns/custom-servers
/api/v1/settings/dns/default-suffix
/api/v1/settings/dns/proxy-enabled
/api/v1/settings/dns/zones
/api/v1/settings/user/connect-auth
/api/v1/settings/user/device-allowance
/api/v1/settings/user/device-allowance-force-update
/api/v1/settings/user/device-enforcement
/api/v1/settings/user/profile-distribution
/api/v1/settings/users/connection-timeout
/api/v1/settings/wpc/client-options
/api/v1/settings/wpc/default-region
/api/v1/settings/wpc/domain-routing-subnet
/api/v1/settings/wpc/snat
/api/v1/settings/wpc/subnet
/api/v1/settings/wpc/topology
Parameter Changes
Resource | Attribute | Beta (Old) | v1.0.0 (New) |
|---|---|---|---|
User Group | Connect Auth | AUTH | ON_PRIOR_AUTH |
User Group | Connect Auth | AUTO | NO_AUTH |
User Group | Connect Auth | STRICT_AUTH | EVERY_TIME |
User Group, Network, Host | Internet Access | BLOCKED | RESTRICTED_INTERNET |
User Group, Network, Host | Internet Access | GLOBAL_INTERNET | SPLIT_TUNNEL_OFF |
User Group, Network, Host | Internet Access | LOCAL | SPLIT_TUNNEL_ON |
Location Context | default_policy | default_check | |
Location Context | country_policy | country_check | |
Location Context | ip_policy | ip_check |
Change in Bulk Operations
Beta:
Allowed bulk creation for Users, IP Services, and Applications.
v1.0.0:
Bulk operations removed.
Resources must be created individually.
Changes in /page Endpoints
Beta | v1.0.0 |
|---|---|
|
|
Expanded Devices Endpoints
New Endpoints for Device Management:
GET /api/v1/devices→ Retrieves all devices.GET /api/v1/devices/{id}→ Retrieves a specific device.POST /api/v1/devices/{id}→ Update an existing device.
Rate Limit Changes
Rate limits are written as three numbers separated by '/'. The first number represents the rate at which requests are replenished (requests per second), the second number represents the period (in seconds) after which requests start replenishing, and the third number represents the initial number of requests allowed before replenishment. For example, 1/4/20 represents that 20 requests will be allowed initially, followed by a 4-second period, after which one request per second will be replenished.
Beta:
Rate limits are applied per API key.
Read Operations: 4/2/250
Update Operations: 1/15/20
v1.0.0:
Rate limits are applied per tenant.
Read Operations: 1/1/100
Update Operations: 1/4/20
Conclusion
The migration from Beta to API v1.0.0 introduces changes in endpoint structure, authentication, bulk operations, and rate limits. Ensure that your integrations are updated accordingly.
For further details, refer to the official API documentation.