Create a Grouped Gateway

Time	Status	User Agent
Retrieving recent requests…

Request body for creating a Grouped Gateway.

Human-readable name.

IDs of member Gateways (minimum 2).

Tenant IDs to grant access. Validated against the caller's organization — 403 if mismatched.

ACTIVE_STANDBY — traffic goes to the primary gateway; failover to secondary on failure. RANDOM — traffic is distributed randomly across gateways. NEAREST — traffic routes to the geographically closest gateway.

Required gateway stability before failover, in seconds, for the ACTIVE_STANDBY strategy. Must be one of the listed durations (mirrors the Jamf console). Required on create even for RANDOM/NEAREST, where it is ignored.

The tenant UUID identifier. Send it to address tenant scope. This API is also published at environment scope — send that scope's header instead. Send exactly one scope header per request.

The environment UUID identifier. Send it to address environment scope. This API is also published at tenant scope — send that scope's header instead. Send exactly one scope header per request.

Resource created. Body contains id and href; Location header points to the new resource.

Bad request — validation error. Common codes: INVALID_FIELD (schema or constraint violation), IPSEC_SECRET_CLEAR_NOT_SUPPORTED (explicit null sent for ipsec.left.secret), IPSEC_REMOVAL_NOT_SUPPORTED (explicit null sent for ipsec on a gateway that has IPSec configured).

Forbidden — the caller's organization does not own one or more of the supplied tenantIds. Any mismatch rejects the entire request.

Conflict — request is valid but cannot be processed due to current state. Common codes: HOSTNAME_CONFLICT — hostname already assigned to another App; BARE_IPS_CONFLICT — POST/PATCH app: one or more of the provided bareIps IP ranges conflict with an existing app (field: bareIps); DEDICATED_IPS_LIMIT — dedicatedIps.enabled: true quota exhausted; IPSEC_LIMIT — IPSec egress tunnel limit reached; TLD_LIMIT_EXCEEDED — limit on distinct top-level domains exceeded; MISSING_CATEGORY_NAME — categoryName does not match any category returned by GET /v1/categories; MISSING_SKU2_FOR_RISK_CONTROL — risk controls require SKU2 entitlement not held by this customer; MISSING_USER_GROUPS — one or more assignment group IDs do not exist for this customer; UNSUPPORTED_BARE_IP_IN_REFERENCED_GATEWAY_IPSEC_CONFIG — a bareIps subnet is not covered by the referenced gateway's IPSec tunnel right.subnets; GATEWAY_REFERENCED_BY_ACCESS_POLICIES — DELETE gateway: still referenced by one or more Access Policies; GATEWAY_REFERENCED_BY_GROUPED_GATEWAYS — DELETE gateway: still a member of one or more grouped gateways; GATEWAY_REFERENCED_BY_DNS_ZONES — DELETE gateway: still referenced by one or more Custom DNS Zones; GROUPED_GATEWAY_REFERENCED_BY_ACCESS_POLICIES — DELETE grouped-gateway: still referenced by one or more Access Policies; GROUPED_GATEWAY_REFERENCED_BY_DNS_ZONES — DELETE grouped-gateway: still referenced by one or more Custom DNS Zones; CUSTOMERS_REFERENCED_BY_ACCESS_POLICIES — PATCH gateway or grouped gateway: an unassigned customer is still referenced by one or more Access Policies; CUSTOMERS_REFERENCED_BY_GROUPED_GATEWAYS — PATCH gateway: an unassigned customer still uses this gateway via a grouped gateway; CUSTOMERS_REFERENCED_BY_DNS_ZONES — PATCH gateway or grouped gateway: an unassigned customer is still referenced by one or more Custom DNS Zones; CUSTOMERS_FROM_DIFFERENT_ORGANIZATIONS — PATCH gateway: the provided customers belong to different organizations; only customers from the same organization may be assigned together; GATEWAYS_TUNNEL_FLAG_MISMATCH — PATCH grouped-gateway: the combined set of referenced gateways (supplied plus the group's existing members) does not all share the same tunneled flag; distinct from 422 MIXED_TUNNEL_TYPES, which rejects a supplied gatewayIds set that is itself mixed (field: gatewayIds); IPSEC_CONFIG_DUPLICATE — POST/PATCH gateway: a gateway with the same IPSec configuration already exists (field: ipsec); PREDEFINED_APP_NOT_FOUND — POST app: predefinedAppId does not resolve to an existing predefined app (field: predefinedAppId). Returned as 409 (not 422): the id is checked against existing predefined apps, not the request's shape. CONFLICT — generic conflict fallback; emitted for conflict cases not covered by a specific code above (e.g. removing the contact from a dedicated VPN route). Note: inaccessible gateway IDs in request bodies return 422 GATEWAY_NOT_FOUND, not 409. An unresolvable predefinedAppId is the deliberate exception — it returns 409 PREDEFINED_APP_NOT_FOUND.

Unprocessable entity — request is syntactically valid but violates a cross-field business constraint. Error codes: GATEWAY_NOT_FOUND — a gateway ID in routing.gatewayId or gatewayIds is not accessible to this customer (applies to Apps and Grouped Gateways; returns 422 rather than 404 because the ID is in the request body, not the path); SHARED_GATEWAY_MEMBER — one or more gatewayIds refer to shared (Jamf-managed) gateways, which cannot be members of a Grouped Gateway; MIXED_DEDICATED_IPS_TYPES — member gateways have mixed dedicatedIps.enabled values; MIXED_TUNNEL_TYPES — member gateways have mixed tunnel types (some IPSec, some non-IPSec).

Rate limit exceeded. Retry after the period indicated by Retry-After.

201Resource created. Body contains id and href; Location header points to the new resource.

400Bad request — validation error. Common codes: INVALID_FIELD (schema or constraint violation), IPSEC_SECRET_CLEAR_NOT_SUPPORTED (explicit null sent for ipsec.left.secret), IPSEC_REMOVAL_NOT_SUPPORTED (explicit null sent for ipsec on a gateway that has IPSec configured).

403Forbidden — the caller's organization does not own one or more of the supplied tenantIds. Any mismatch rejects the entire request.

429Rate limit exceeded. Retry after the period indicated by Retry-After.