{"type":"api","title":"List Network Tunnel Groups","meta":{"id":"/apps/pubhub/media/cloud-security-apis-in-eft/9d37d008417d562ab46d4b67547a68457ce288d2/b608b63c-8f99-3c50-a490-501c84f4f333","info":{"title":"Cisco Secure Access Network Tunnel Groups and Regions API","description":"Manage the Secure Access Network Tunnel Groups.","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":"Secure Access"}],"x-parser-conf":{"overview":{"markdownPath":"secure-access/reference/deployments/network-tunnel-groups-overview.md","uri":"secure-access-api-reference-network-tunnel-groups-overview"}},"openapi":"3.0.3","servers":[{"url":"https://api.sse.cisco.com/{basePath}","variables":{"basePath":{"default":"deployments/v2"}}}],"securitySchemes":{"oauthFlow":{"type":"oauth2","description":"client credential flow","flows":{"clientCredentials":{"tokenUrl":"https://api.sse.cisco.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","Secure Access"],"summary":"List Network Tunnel Groups","description":"List the Network Tunnel Groups in the organization.\nIf you enable the `includeStatuses` query parameter in your API request,\nthe response includes the `tunnelsStatus` field.\nThe maximum number of items in a hub's list of tunnel states (`tunnelsStatus`) is 10.","operationId":"listNetworkTunnelGroups","security":[{"oauthFlow":["deployments.networktunnelgroups:read"]}],"parameters":[{"name":"filters","in":"query","description":"Filter the network tunnel groups by one or more properties:\n\n* **name** - The name of a network tunnel group. The value of `name` is a sequence of case-insensitive characters.\n* **exactName** - The sequence of case-insensitive characters that exactly match the name of the network tunnel group.\n Including `exactName` as a filter, causes the system to ignore the `name` filter.\n* **networkTunnelGroupIds** - The comma-separated list of network tunnel group IDs.\n* **exactAuthIdPrefix** - The case-sensitive value of the network tunnel hub auth ID prefix or the IP.\n* **region** - The region for the network tunnel group. The value of `region` is a sequence of case-insensitive characters.\n* **status** - The status of the network tunnel group. Valid values are \"connected\", \"disconnected\", and \"warning\".\n* **duplicateCIDRs** - List the network tunnel groups that have duplicate CIDRs.\n Provide the CIDRs and optionally provide the regional scope and region properties.\n Enabling the regional scope allows the system to find only duplicates within the same region.\n You can not use the `duplicateCIDRs` filter with any other filter.\n\nSpecify the filters in the JSON format.\n\nExample:\n\n```\n{\n \"name\": \"Branch 1 Network Tunnel Group\",\n \"region\": \"us-east-1\"\n}\n```\nor\n\nExample:\n\n```\n{\n \"duplicateCIDRs\":\n {\n \"cidrs\": \"10.0.0.0/8,10.01.0.0/16\",\n \"regionalScope\": true,\n \"region\": \"us-east\"\n }\n}","schema":{"type":"object","description":"The filters for the Network Tunnel Groups.","properties":{"name":{"type":"string","description":"The name of a Network Tunnel Group. The value of `name` is a sequence of case-insensitive characters.","example":"New York Branch Tunnels"},"exactName":{"type":"string","description":"The sequence of case-insensitive characters that exactly match the name of the Network Tunnel Group.\nWhen `exactName` is included as a filter, `name` is ignored.","example":"Branch 1 Tunnel"},"region":{"type":"string","description":"The region for the Network Tunnel Group. The value of `region` is a sequence of case-insensitive characters.","example":"us-east-1"},"networkTunnelGroupIds":{"type":"string","description":"The comma-separated list of Network Tunnel Group IDs.","example":"1234,456"},"exactAuthIdPrefix":{"type":"string","description":"The case-sensitive value of the auth ID prefix (`authIdPrefix`) or IP for the network tunnel Hub.","example":"tunnelprefix1"},"status":{"type":"string","enum":["connected","disconnected","warning"],"description":"The status of the Network Tunnel Group.","example":"connected","$$ref":"#/components/schemas/status"},"duplicateCIDRs":{"type":"string","description":"List the network tunnel groups that have duplicate CIDRs.\nProvide the CIDRs and optionally provide the regional scope and region properties.\nIf the regional scope is enabled, only duplicates in the same region are found.\nYou can not use the `duplicateCIDRs` filter with any other filter.","example":"{ \"cidrs\": \"10.0.0.0/8,10.01.0.0/16\", \"regionalScope\": true, \"region\": us-east }"}},"$$ref":"#/components/schemas/filtersNTGsObject"},"$$ref":"#/components/parameters/filtersNTGs"},{"in":"query","name":"offset","required":false,"description":"An integer that represents the place to start reading in the collection.\nWhen the offset is set to `0`, the system returns the first page from the collection.\nIf the `limit` is 10, the `offset` for the next page is 10.\nThe default value is 0.","schema":{"type":"integer","default":0},"example":10,"$$ref":"#/components/parameters/offset"},{"in":"query","name":"limit","required":false,"description":"An integer that represents the number of records to return in the response.\nThe default value is 10.","schema":{"type":"integer","default":10},"example":25,"$$ref":"#/components/parameters/limit"},{"name":"sortBy","in":"query","description":"Specify the field the system will use to sort the items from the collection in the response.","schema":{"type":"string","enum":["name","status","createdAt","modifiedAt"],"default":"name"},"$$ref":"#/components/parameters/sortBy"},{"in":"query","name":"sortOrder","description":"Specify the sort order (ascending or descending) for the items in the response.","schema":{"type":"string","enum":["asc","desc"],"default":"asc"},"example":"asc","$$ref":"#/components/parameters/sortOrder"},{"name":"includeStatuses","in":"query","description":"Specify whether to include the IPsec tunnel status field (`tunnelsStatus`) for each hub.","schema":{"type":"boolean","default":false},"example":true,"$$ref":"#/components/parameters/includeStatuses"}],"responses":{"200":{"description":"OK","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":"List the Network Tunnel Groups in the organization.","properties":{"data":{"type":"array","description":"The list of Network Tunnel Groups.","items":{"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-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"}},"$$ref":"#/components/schemas/datacenter"},"authId":{"type":"string","readOnly":true,"description":"An IP address or email used to authenticate the tunnel.","example":"newyorkbranchtunnels123@123456-987654321.sse.cisco.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/hubs"},"routing":{"type":"object","required":["type","data"],"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.","properties":{"type":{"type":"string","description":"The type of the route.","enum":["static","bgp","nat"]},"data":{"description":"The list of network CIDR addresses or the autonomous system (AS) number.","oneOf":[{"type":"object","description":"The list of network CIDRs.","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":{"networkCIDRs":["123.111.222.25/24","111.222.39.1/32"]},"$$ref":"#/components/schemas/staticDataResponseObj"},{"type":"object","required":["asNumber"],"description":"The autonomous system (AS) number for the private access tunnels.","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"},"bgpHopCount":{"type":"integer","description":"Indicates how many network hops a packet can traverse before being discarded by a router. It can only\nbe an integer from 1 to 64 and if it is defined, then at least of BGP neighbor CIDR must be provided.","example":10,"$$ref":"#/components/schemas/bgpHopCount"},"bgpNeighborCIDRs":{"type":"array","description":"The list of CIDR netmasks to limit the customer peers that can talk to the headend BGP.\nThe system allows a maximum of 20 CIDRs.","example":["10.0.0.0/8","95.24.45.50/32"],"items":{"type":"string","example":"10.0.0.0/8"},"$$ref":"#/components/schemas/bgpNeighborCIDRs"},"bgpServerSubnets":{"type":"array","description":"The list of BGP server custom IP address ranges applicable only when the device type is `Azure S2S VPN`.\nThe two ranges must be unique and have the `/32` mask.","example":["169.254.0.1/32","169.254.0.1/32"],"items":{"type":"string","example":"169.254.0.1/32"},"$$ref":"#/components/schemas/bgpServerSubnets"}},"example":{"asNumber":"5432"},"$$ref":"#/components/schemas/bgpDataResponseObj"},{"type":"string"}],"example":{"networkCIDRs":["123.111.222.25/24","111.222.39.1/32"]}}},"example":{"type":"bgp","data":{"asNumber":"5432"}},"$$ref":"#/components/schemas/routingResponse"},"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-east-1","status":"connected","hubs":[{"id":987654321,"isPrimary":true,"datacenter":{"name":"us-east-1"},"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"},"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/networkTunnelGroupListResponse"},"example":[{"id":4561237892,"name":"New York Branch Tunnels","organizationId":123456,"deviceType":"ASA","region":"us-east-1","status":"connected","hubs":[{"id":987654321,"isPrimary":true,"datacenter":{"name":"us-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:50: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"}]},"offset":{"type":"integer","description":"An integer that represents the place to start reading in the collection.","example":1},"limit":{"type":"integer","description":"The number of records returned on a page.","example":100},"total":{"type":"integer","description":"The total number of records returned.","example":100}},"example":{"data":[{"id":4561237892,"name":"New York Branch Tunnels","organizationId":123456,"deviceType":"ASA","region":"us-east-1","status":"connected","hubs":[{"id":987654321,"isPrimary":true,"datacenter":{"name":"us-east-1","ip":"54.145.27.13"},"authId":"newyorkbranchtunnels123@123456-987654321.sse.cisco.com"},{"id":147852369,"isPrimary":false,"datacenter":{"name":"us-central-1","ip":"25.132.42.15"},"authId":"newyorkbranchtunnels123@123456-147852369.sse.cisco.com"}],"routing":{"type":"static","data":{"networkCIDRs":["123.111.222.25/24","111.222.39.1/32"]}}}],"offset":0,"limit":10,"total":1},"$$ref":"#/components/schemas/networkTunnelGroupsList"},"example":{"data":[{"id":4561237892,"name":"New York Branch Tunnels","organizationId":123456,"deviceType":"ASA","region":"us-east-1","status":"warning","hubs":[{"id":987654321,"isPrimary":true,"datacenter":{"name":"us-east-1"},"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"},"authId":"newyorkbranchtunnels123@123456-147852369.sse.cisco.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"}],"offset":0,"limit":10,"total":1}}}},"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":"\"includeStatuses\" query param is invalid"},"requestId":{"type":"string","description":"The ID of the request.","example":"7d318524-d5a4-4fd8-8b29-ad295b2f035b"}}},{"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":{"limit":{"type":"string","description":"Indicates the problem with the limit.","example":"Value should be a number from 1 to 200."},"offset":{"type":"string","description":"Indicates the problem with the offset.","example":"Attribute value is invalid."},"sortBy":{"type":"string","description":"Indicates the problem with the sortBy.","example":"must be one of [name status createdAt modifiedAt]."},"authId":{"type":"string","description":"Indicates the problem with the sortOrder.","example":"must be one of [asc desc]."}}}}}],"$$ref":"#/components/schemas/400ListError"}}},"$$ref":"#/components/responses/400ListError"},"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"},"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":"listNetworkTunnelGroups","method":"get","path":"/networktunnelgroups"}}