Locations
A location is a site: a data center, branch office, cloud region, or anywhere services are hosted or reached via a Customer Connect connector. A location lives either under a customer or directly under a provider; either way it behaves identically.
What a location is (and isn't)
A location is purely a logical grouping. It's metadata that scopes connectors and helps you organize them. Nothing is provisioned on the network for a location on its own. The network-level work happens when a connector is created inside the location.
Customer locations vs. provider locations
A location attached to a customer represents a tenant's site (a branch office, a regional cloud, etc.). A location attached directly to a provider represents provider-owned infrastructure (internal gateways, shared egress, lab and monitoring connectors) that doesn't belong to any single tenant. Both kinds of locations:
- Host Connectors, which in turn host Applications.
- Can be the source or destination of an access policy, and can be mixed freely on the same access policy.
The location's providerId is the same in both cases; what differs is whether a customer sits between the provider and
the location.
Optional geographic metadata (address, longitude, latitude) can be attached to a physical location for display and
mapping purposes. longitude and latitude must be provided together.
A location can also be marked as virtual, meaning it's hosted in a public cloud rather than a physical site. Virtual
locations carry cloudProvider (e.g. AWS, GCP, Azure) and cloudRegion (e.g. us-east-1) instead of an
address. The two modes are mutually exclusive: cloudProvider and cloudRegion are only allowed when virtual is
true, and address is only allowed when virtual is false.
A location can be temporarily suspended with PUT/PATCH /locations/{id}/pause, and re-enabled with the matching /resume endpoint. Both require the connectivity permission on
the location — a distinct action from update, so an operator can suspend traffic without being able to edit the location (see
Roles and grants).
Pausing suspends every access policy touching the location or a connector at it by pruning its live Ziti dial projection, so traffic stops flowing while the policy definitions are
retained; resuming re-materializes them. The affected access policies report this through their own response-only enabled flag (see
Access policies).
The location's enabled flag is itself response-only, defaults to true at creation, and the per-connector state remains independent. Pausing an already-paused location (or
resuming an already-running one) is a no-op.
Fields
| Field | Description | Example |
|---|---|---|
id | Unique ID assigned at create time | 2c4d6e8f-1a3b-4c5d-9e0f-1a2b3c4d5e6f |
customerId | Parent customer | b34a5e6f-7890-4abc-def0-1234567890ab |
providerId | Denormalized from the parent customer — set on create, immutable | 8b14d4f9-3a52-4b91-8e7c-d3e44b5c1f2a |
name | Human-readable location name, unique within the customer | Boston HQ |
description | Optional free-form description | Primary East Coast data center |
address | Optional street address (up to 1000 characters) | 100 Federal St, Boston, MA 02110 |
longitude | Optional decimal-degree longitude in [-180, 180] | -71.0589 |
latitude | Optional decimal-degree latitude in [-90, 90] | 42.3601 |
virtual | Whether this is a virtual location with no physical presence | false |
cloudProvider | Cloud provider hosting a virtual location (requires virtual=true) | AWS |
cloudRegion | Region of the cloud provider (requires virtual=true) | us-east-1 |
enabled | Whether the location is enabled. Response-only; toggled via the /pause and /resume endpoints, not on update. false suspends the dial projection of every access policy touching it | true |
ownerIdentityId, createdAt, updatedAt | Standard lifecycle fields |
Access policy targets
Access policies link a source to a destination. A location can be on either side:
- A location source means "any connector at this location can originate this access policy".
- A location destination means "any connector at this location can be reached by this access policy".
This is what lets a provider publish an application to every site of a customer with a single access policy.
Resource counts
Every location response includes a counts object with the number of connectors, applications, source access policies,
and destination access policies scoped to the location (sourceAccessPolicies and destinationAccessPolicies).
Applications are aggregated across every connector at the location. Source and destination access policy counts are
independent: an access policy with the same location on both sides is counted in each. It's populated on every list and
get response, so dashboards and navigation UIs can render counts without paging through the underlying collections.