{"type":"api","title":"Create Network Tunnel Group","meta":{"id":"/apps/pubhub/media/cloud-security-gov/9ead083ce611c254ac9201d1e76003bd3d4b4b6b/9ac6e75b-d8b8-3687-ab41-997436170333","info":{"title":"Cisco Umbrella for Government Network Tunnel Groups and Regions API","description":"Manage the Network Tunnel Groups in the organization.","version":"1.0.0","contact":{"name":"Cloud Security Developer Community"}},"security":[{"oauthFlow":[]}],"tags":[{"name":"Network Tunnel Groups","description":"Network Tunnel Groups API endpoints"},{"name":"Network Tunnel Groups Regions","description":"Network Tunnel Groups Regions API endpoints"},{"name":"Network Tunnel Groups State","description":"Network Tunnel Groups State API endpoints"},{"name":"Network Tunnel Groups Peer State","description":"Network Tunnel Groups Peer State API endpoints"},{"name":"Umbrella"}],"x-parser-conf":{"overview":{"markdownPath":"reference/deployments/network-tunnel-groups-overview.md","uri":"umbrella-api-reference-network-tunnel-groups-regions-overview"}},"openapi":"3.0.3","servers":[{"url":"https://api.umbrellagov.com/{basePath}","variables":{"basePath":{"default":"deployments/v2"}}}],"securitySchemes":{"oauthFlow":{"type":"oauth2","description":"client credential flow","flows":{"clientCredentials":{"tokenUrl":"https://api.umbrellagov.com/auth/v2/token","scopes":{"deployments.networktunnelgroups:read":"Read network tunnel groups deployments","deployments.networktunnelgroups:write":"Write network tunnel groups deployments","deployments.regions:read":"Read regions for network tunnel groups deployments"}}}}}},"spec":{"tags":["Network Tunnel Groups","Umbrella"],"summary":"Create Network Tunnel Group","description":"Create a Network Tunnel Group in the organization.","operationId":"addNetworkTunnelGroup","security":[{"oauthFlow":["deployments.networktunnelgroups:write"]}],"requestBody":{"description":"Create the Network Tunnel Group.","required":true,"content":{"application/json":{"schema":{"type":"object","description":"Create the Network Tunnel Group with the specific properties.","required":["name","region","authIdPrefix","passphrase"],"properties":{"name":{"type":"string","description":"The name of the Network Tunnel Group.\nA Network Tunnel Group name is a sequence of 1–50 characters. The `name` field cannot have any special characters other than spaces and hyphens.","example":"New York Branch Tunnels","$$ref":"#/components/schemas/name"},"region":{"type":"string","description":"The name of the region that the system uses to obtain the primary and secondary data centers for the Hubs.","example":"us-gov-east-1","$$ref":"#/components/schemas/region"},"deviceType":{"type":"string","description":"The type of device that establishes the network tunnel. The default value is `other`.","enum":["ASA","AWS S2S VPN","AZURE S2S VPN","FTD","ISR","Meraki MX","Viptela cEdge","Viptela vEdge","other"],"example":"ASA","$$ref":"#/components/schemas/deviceType"},"authIdPrefix":{"description":"An IP address or ID for the network tunnel. The value of `authIdPrefix` is used to generate the ID portion of\nthe Pre-Shared Key (PSK).\n\n* If you provide an IP, then you should include two IP addresses.\n* If you provide a string, ensure that the string is a sequence of 8–100 characters.\n The string should not have any special characters besides the period(**.**), underscore(**_**), and dash(**-**) characters.","oneOf":[{"type":"string","description":"A descriptive label for the tunnel.","example":"networktunnelone"},{"type":"array","description":"A list of the IP addresses for the tunnel.","items":{"type":"string","description":"An IP address for the tunnel.","example":"20.21.23.24"},"example":["20.21.23.24","30.21.25.26"]}]},"passphrase":{"type":"string","description":"The passphrase for the primary and secondary tunnels.\nProvide a sequence of characters where the length of the passphrase is 16–64 characters.\nThe passphrase must contain at least one upper and one lowercase letter as well as one numeral.\nThe passphrase may not include special characters.","example":"t3stingTunn3lNow"},"routing":{"oneOf":[{"type":"object","description":"The nat routing.","required":["type","data"],"properties":{"type":{"type":"string","enum":["nat"],"example":"nat"},"data":{"type":"object"}},"example":{"type":"nat","data":{}},"$$ref":"#/components/schemas/natTypeDataRequestObj"},{"type":"object","description":"The list of network CIDRs.","required":["type","data"],"properties":{"type":{"type":"string","enum":["static"],"example":"static"},"data":{"type":"object","required":["networkCIDRs"],"properties":{"networkCIDRs":{"type":"array","description":"The public and private address ranges that are used internally by your organization.","items":{"type":"string","example":"123.111.222.25/24"},"example":["123.111.222.25/24"],"$$ref":"#/components/schemas/networkCIDRS"}}}},"example":{"type":"static","data":{"networkCIDRs":["123.111.222.25/24","111.222.39.1/32"]}},"$$ref":"#/components/schemas/staticTypeDataRequestObj"},{"type":"object","description":"The asNumber for routing when BGP.","required":["type","data"],"properties":{"type":{"type":"string","enum":["bgp"],"example":"bgp"},"data":{"type":"object","required":["asNumber"],"properties":{"asNumber":{"type":"string","description":"The border gateway protocol (BGP) autonomous system (AS) number for private access network tunnels.\nOnly required for the `bgp` routing type. Any other routing types except `bgp` are ignored.\nSpecify an integer between 0–65536.","example":"5432","$$ref":"#/components/schemas/asNumber"}}}},"example":{"type":"bgp","data":{"asNumber":"5432"}},"$$ref":"#/components/schemas/bgpTypeDataRequestObj"}],"description":"The routing information for the network tunnel.\nThe `nat` routing type is used when the tunnels in your organization connect to network spaces with overlapping IP address spaces.\n\nIf the routing type is `nat`, then set the `data` field to null or an empty string.\nIf the routing type is `bgp`, then set the `data` field with the `asNumber` field.\nIf the routing type is `static`, then set the `data` field with the `networkCIDRS` field.","example":{"type":"bgp","data":{"asNumber":"5432"}},"$$ref":"#/components/schemas/routingRequestWithTypes"}}},"example":{"name":"Test Tunnel One","region":"us-gov-east-1","authIdPrefix":"networktunnelone","passphrase":"t3stingTunn3lNow"}}},"$$ref":"#/components/requestBodies/networkTunnelGroupCreateRequest"},"responses":{"201":{"description":"Created","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","description":"The properties of the Network Tunnel Group in the organization.","properties":{"id":{"type":"integer","description":"The ID of the Network Tunnel Group.","readOnly":true,"example":456123789,"$$ref":"#/components/schemas/id"},"name":{"type":"string","description":"The name of the Network Tunnel Group.\nA Network Tunnel Group name is a sequence of 1–50 characters. The `name` field cannot have any special characters other than spaces and hyphens.","example":"New York Branch Tunnels","$$ref":"#/components/schemas/name"},"organizationId":{"type":"integer","description":"The ID of the organization.","readOnly":true,"example":123556,"$$ref":"#/components/schemas/organizationId"},"deviceType":{"type":"string","description":"The type of device that establishes the network tunnel. The default value is `other`.","enum":["ASA","AWS S2S VPN","AZURE S2S VPN","FTD","ISR","Meraki MX","Viptela cEdge","Viptela vEdge","other"],"example":"ASA","$$ref":"#/components/schemas/deviceType"},"region":{"type":"string","description":"The name of the region that the system uses to obtain the primary and secondary data centers for the Hubs.","example":"us-gov-east-1","$$ref":"#/components/schemas/region"},"status":{"type":"string","enum":["connected","disconnected","warning"],"description":"The status of the Network Tunnel Group.","example":"connected","$$ref":"#/components/schemas/status"},"hubs":{"type":"array","description":"The list of Hubs for a Network Tunnel Group.\nOnly one Hub is the primary data center.","items":{"type":"object","description":"The properties of the Hub.","properties":{"id":{"type":"integer","readOnly":true,"description":"The ID of the Hub.","example":987654321,"$$ref":"#/components/schemas/hubId"},"isPrimary":{"type":"boolean","description":"Specifies whether the Hub is a primary data center.","readOnly":true,"example":true,"$$ref":"#/components/schemas/isPrimary"},"datacenter":{"type":"object","properties":{"name":{"type":"string","description":"The name of the data center for the Hub.","readOnly":true,"example":"dc-1-0-0"},"ip":{"type":"string","description":"The IP address of the data center for the Hub.","readOnly":true,"example":"54.145.27.13"}},"$$ref":"#/components/schemas/datacenterWithIP"},"authId":{"type":"string","readOnly":true,"description":"An IP address or email used to authenticate the tunnel.","example":"newyorkbranchtunnels123@123456-987654321.umbrellagov.com","$$ref":"#/components/schemas/authId"},"status":{"type":"object","description":"The properties of a Hub for the Network Tunnel Group.","required":["time","status"],"properties":{"time":{"type":"string","readOnly":true,"format":"date-time","description":"The date and time (UTC time, with milliseconds) when the state event record was generated.","example":"2023-06-30T16:07:07.222Z"},"status":{"type":"string","readOnly":true,"description":"The high-level status of the Hub:\n* UP - The hub is active.\n* DOWN - The hub is inactive.\n","enum":["UP","DOWN"],"example":"UP"}},"example":{"time":"2023-06-30T16:07:07.222Z","status":"UP"},"$$ref":"#/components/schemas/hubState"},"tunnelsCount":{"type":"integer","description":"The number of tunnels in the hub.","readOnly":true,"example":5,"$$ref":"#/components/schemas/tunnelsCount"}}},"$$ref":"#/components/schemas/hubsWithIP"},"routing":{"oneOf":[{"type":"object","description":"The nat routing.","required":["type","data"],"properties":{"type":{"type":"string","enum":["nat"],"example":"nat"},"data":{"type":"object"}},"example":{"type":"nat","data":{}},"$$ref":"#/components/schemas/natTypeDataRequestObj"},{"type":"object","description":"The list of network CIDRs.","required":["type","data"],"properties":{"type":{"type":"string","enum":["static"],"example":"static"},"data":{"type":"object","required":["networkCIDRs"],"properties":{"networkCIDRs":{"type":"array","description":"The public and private address ranges that are used internally by your organization.","items":{"type":"string","example":"123.111.222.25/24"},"example":["123.111.222.25/24"],"$$ref":"#/components/schemas/networkCIDRS"}}}},"example":{"type":"static","data":{"networkCIDRs":["123.111.222.25/24","111.222.39.1/32"]}},"$$ref":"#/components/schemas/staticTypeDataRequestObj"},{"type":"object","description":"The asNumber for routing when BGP.","required":["type","data"],"properties":{"type":{"type":"string","enum":["bgp"],"example":"bgp"},"data":{"type":"object","required":["asNumber"],"properties":{"asNumber":{"type":"string","description":"The border gateway protocol (BGP) autonomous system (AS) number for private access network tunnels.\nOnly required for the `bgp` routing type. Any other routing types except `bgp` are ignored.\nSpecify an integer between 0–65536.","example":"5432","$$ref":"#/components/schemas/asNumber"}}}},"example":{"type":"bgp","data":{"asNumber":"5432"}},"$$ref":"#/components/schemas/bgpTypeDataRequestObj"}],"description":"The routing information for the network tunnel.\n\nIf the routing type is `nat`, then the `data` field is empty.\nIf the routing type is `bgp`, then `data` includes the `asNumber` field.\nIf the routing type is `static`, then `data` includes the `networkCIDRs` field.","example":{"type":"bgp","data":{"asNumber":"5432"}},"$$ref":"#/components/schemas/routingResponseWithTypes"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"The date and time (timestamp) when the network tunnel group was created.","example":"2024-06-12T18:04:23Z","$$ref":"#/components/schemas/createdAt"},"modifiedAt":{"type":"string","format":"date-time","readOnly":true,"description":"The date and time of the last update (timestamp) for the network tunnel group.","example":"2024-06-25T15:21:32Z","$$ref":"#/components/schemas/modifiedAt"}},"example":{"id":4561237892,"name":"New York Branch Tunnels","organizationId":123456,"deviceType":"ASA","region":"us-gov-east-1","status":"connected","hubs":[{"id":987654321,"isPrimary":true,"datacenter":{"name":"us-gov-east-1","ip":"54.145.27.13"},"authId":"newyorkbranchtunnels123@123456-987654321.sse.cisco.com","status":{"status":"UP","time":"2025-02-05T17:53:05Z"},"tunnelsCount":5},{"id":147852369,"isPrimary":false,"datacenter":{"name":"us-central-1","ip":"25.132.42.15"},"authId":"newyorkbranchtunnels123@123456-147852369.sse.cisco.com","status":{"status":"UP","time":"2025-02-05T17:53:05Z"},"tunnelsCount":5}],"routing":{"type":"static","data":{"networkCIDRs":["123.111.222.25/24","111.222.39.1/32"]}},"createdAt":"2024-06-12T18:04:23Z","modifiedAt":"2024-06-25T15:21:32Z"},"$$ref":"#/components/schemas/networkTunnelGroupResponse"},"example":{"id":4561237892,"name":"New York Branch Tunnels","organizationId":123456,"deviceType":"ASA","region":"us-gov-east-1","status":"disconnected","hubs":[{"id":987654321,"isPrimary":true,"datacenter":{"name":"us-gov-east-1","ip":"54.145.27.13"},"authId":"newyorkbranchtunnels123@123456-987654321.umbrellagov.com","status":{"status":"DOWN","time":"2025-02-05T17:53:05Z"},"tunnelsCount":0},{"id":147852369,"isPrimary":false,"datacenter":{"name":"us-gov-east-1","ip":"25.132.42.15"},"authId":"newyorkbranchtunnels123@123456-147852369.umbrellagov.com","status":{"status":"DOWN","time":"2025-02-05T17:53:05Z"},"tunnelsCount":0}],"routing":{"type":"static","data":{"networkCIDRs":["123.111.222.25/24","111.222.39.1/32"]}},"createdAt":"2024-06-12T18:04:23Z","modifiedAt":"2024-06-25T15:21:32Z"}}}},"400":{"description":"Bad Request","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Validation Error"},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"},"validationErrors":{"type":"object","properties":{"name":{"type":"string","description":"Indicates the problem with the tunnel name.","example":"Attribute value is blank."},"region":{"type":"string","description":"Indicates the problem with the region.","example":"Attribute value does not exist."},"deviceType":{"type":"string","description":"Indicates the problem with the device type.","example":"Attribute value is invalid."},"authId":{"type":"string","description":"Indicates the problem with the tunnel auth ID.","example":"Attribute value is invalid."},"passphrase":{"type":"string","description":"Indicates the problem with the passphrase.","example":"Attribute value is invalid."},"routing":{"type":"string","description":"Indicates the problem with the routing.","example":"Attribute value is invalid."}}}}},{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Invalid request body."},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}}}],"$$ref":"#/components/schemas/400ValidationError"}}},"$$ref":"#/components/responses/400ValidationError"},"401":{"description":"Unauthorized","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Authorization token is invalid."},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}},"$$ref":"#/components/schemas/401Error"}}},"$$ref":"#/components/responses/401Error"},"403":{"description":"Forbidden","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Access Forbidden"},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}},"$$ref":"#/components/schemas/403Error"}}},"$$ref":"#/components/responses/403Error"},"404":{"description":"Not Found","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Not Found"},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}},"$$ref":"#/components/schemas/404Error"}}},"$$ref":"#/components/responses/404Error"},"409":{"description":"Duplicate network tunnel group name.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Conflict–Network tunnel group name must be unique."},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}},"$$ref":"#/components/schemas/409Error"}}}},"500":{"description":"Internal Server Error","headers":{"Content-Type":{"schema":{"type":"string"},"description":"The MIME content type of the response body.","example":"application/json","$$ref":"#/components/headers/Content-Type"},"Date":{"schema":{"type":"string","pattern":"^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$"},"description":"The timestamp of the response.","example":"2023-03-14T18:34:25Z","$$ref":"#/components/headers/Date"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message explaining the reason for failure.","example":"Internal Server Error"},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}},"$$ref":"#/components/schemas/500Error"}}},"$$ref":"#/components/responses/500Error"}},"__originalOperationId":"addNetworkTunnelGroup","method":"post","path":"/networktunnelgroups"}}