Cloud Security Gov

Network Tunnel Groups and Regions

List Network Tunnel Groups

GET https://api.umbrellagov.com/deployments/v2/networktunnelgroups

Description

List the Network Tunnel Groups in the organization. If you enable the includeStatuses query parameter on your API request, then the tunnelsStatus field is included in the response. The maximum number of items in a hub's list of tunnel states (tunnelsStatus) is 10.

Query Parameters

filters
(Optional, object)
Filter the network tunnel groups by one or more properties:
- name - The name of a network tunnel group. The value of name is a sequence of case-insensitive characters.
- exactName - The sequence of case-insensitive characters that exactly match the name of the network tunnel group. When exactName is included as a filter, the name filter is ignored.
- networkTunnelGroupIds - The comma-separated list of network tunnel group IDs.
- exactAuthIdPrefix - The case-sensitive value of the network tunnel hub auth ID prefix or the IP.
- region - The region for the network tunnel group. The value of region is a sequence of case-insensitive characters.
- status - The status of the network tunnel group. Valid values are "connected", "disconnected", and "warning".
- duplicateCIDRs - List the network tunnel groups that have duplicate CIDRs. Provide the CIDRs and optionally provide the regional scope and region properties. If the regional scope is enabled, only duplicates in the same region are found. You can not use the duplicateCIDRs filter with any other filter.
Specify the filters in the JSON format.

Example:
Code Snippet
Copy{ "name": "Branch 1 Network Tunnel Group", "region": "us-gov-east-1" }
or

Example:
Code Snippet
Copy{ "duplicateCIDRs": { "cidrs": "10.0.0.0/8,10.01.0.0/16", "regionalScope": true, "region": "us-gov-east-1" } }
offset
(Optional, integer) An integer that represents the place to start reading in the collection. When the offset is 0, the first page is returned from the collection. If the limit is 10, the offset for the next page is 10. The default value is 0.
limit
(Optional, integer) An integer that represents the number of records to return in the response. The default value is 10.
sortBy
(Optional, string) Specify the field that will be used to sort the items from the collection in the response.
sortOrder
(Optional, string) Specify the sort order (ascending or descending) for the items in the response.
includeStatuses
(Optional, boolean) Specify whether to include the IPsec tunnel status field (tunnelsStatus) for each hub.

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/deployments/v2/networktunnelgroups' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (`object`)

data
(Optional, array (object)) The list of Network Tunnel Groups.
- id
  (Optional, integer) The ID of the Network Tunnel Group.
- name
  (Optional, string) The name of the Network Tunnel Group. A Network Tunnel Group name is a sequence of 1–50 characters. The name field cannot have any special characters other than spaces and hyphens.
- organizationId
  (Optional, integer) The ID of the organization.
- deviceType
  (Optional, string) The type of device that establishes the network tunnel. The default value is other.
- region
  (Optional, string) The name of the region that is used to get the primary and secondary data centers for the Hubs.
- status
  (Optional, string) The status of the Network Tunnel Group.
- hubs
  (Optional, array (object)) The list of Hubs for a Network Tunnel Group. Only one Hub is the primary data center.
  - id
    (Optional, integer) The ID of the Hub.
  - isPrimary
    (Optional, boolean) Specifies whether the Hub is a primary data center.
  - datacenter
    (Optional, object)
  - authId
    (Optional, string) An IP address or email used to authenticate the tunnel.
  - status
    (Optional, object) The properties of a Hub for the Network Tunnel Group.
  - tunnelsCount
    (Optional, integer) The number of tunnels in the hub.
- routing
  (Optional, oneOf) The routing information for the network tunnel.
  
  If the routing type is nat, then the data field is empty. If the routing type is bgp, then data includes the asNumber field. If the routing type is static, then data includes the networkCIDRs field.
  - oneOf-1
    - type
      (Required, string)
    - data
      (Required, object)
  - oneOf-2
    - type
      (Required, string)
    - data
      (Required, object)
  - oneOf-3
    - type
      (Required, string)
    - data
      (Required, object)
- createdAt
  (Optional, string) The date and time (timestamp) when the network tunnel group was created.
- modifiedAt
  (Optional, string) The date and time of the last update (timestamp) for the network tunnel group.
offset
(Optional, integer) An integer that represents the place to start reading in the collection.
limit
(Optional, integer) The number of records returned on a page.
total
(Optional, integer) The total number of records returned.

Response Sample

Click to view the sample response (200, OK)

Code Snippet

Copy{
    "data": [
        {
            "id": 4561237892,
            "name": "New York Branch Tunnels",
            "organizationId": 123456,
            "deviceType": "ASA",
            "region": "us-gov-east-1",
            "status": "warning",
            "hubs": [
                {
                    "id": 987654321,
                    "isPrimary": true,
                    "datacenter": {
                        "name": "us-gov-east-1"
                    },
                    "authId": "newyorkbranchtunnels123@123456-987654321.umbrellagov.com",
                    "status": {
                        "status": "UP",
                        "time": "2025-02-05T17:53:05Z"
                    },
                    "tunnelsCount": 5
                },
                {
                    "id": 147852369,
                    "isPrimary": false,
                    "datacenter": {
                        "name": "us-gov-east-1"
                    },
                    "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"
        }
    ],
    "offset": 0,
    "limit": 10,
    "total": 1
}

Create Network Tunnel Group

POST https://api.umbrellagov.com/deployments/v2/networktunnelgroups

Description

Create a Network Tunnel Group in the organization.

Request Body Schema (`object`)

name
(Required, string) The name of the Network Tunnel Group. A Network Tunnel Group name is a sequence of 1–50 characters. The name field cannot have any special characters other than spaces and hyphens.
region
(Required, string) The name of the region that is used to get the primary and secondary data centers for the Hubs.
deviceType
(Optional, string) The type of device that establishes the network tunnel. The default value is other.
authIdPrefix
(Required, oneOf)
An IP address or ID for the network tunnel. The value of authIdPrefix is used to generate the ID portion of the Pre-Shared Key (PSK).
- If you provide an IP, then you should include two IP addresses.
- If you provide a string, ensure that the string is a sequence of 8–100 characters. The string should not have any special characters besides the period(.), underscore(_), and dash(-) characters.
- oneOf-1
  - (Optional, string) A descriptive label for the tunnel.
- oneOf-2
passphrase
(Required, string) The passphrase for the primary and secondary tunnels. Provide a sequence of characters where the length of the passphrase is 16–64 characters. The passphrase must contain at least one upper and one lowercase letter as well as one numeral. The passphrase may not include special characters.
routing
(Optional, oneOf) The routing information for the network tunnel. The nat routing type is used when the tunnels in your organization connect to network spaces with overlapping IP address spaces.

If the routing type is nat, then set the data field to null or an empty string. If the routing type is bgp, then set the data field with the asNumber field. If the routing type is static, then set the data field with the networkCIDRS field.
- oneOf-1
  - type
    (Required, string)
  - data
    (Required, object)
- oneOf-2
  - type
    (Required, string)
  - data
    (Required, object)
- oneOf-3
  - type
    (Required, string)
  - data
    (Required, object)

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request POST --url 'https://api.umbrellagov.com/deployments/v2/networktunnelgroups' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json' \
-d '{
    "name": "Test Tunnel One",
    "region": "us-gov-east-1",
    "authIdPrefix": "networktunnelone",
    "passphrase": "t3stingTunn3lNow"
}'

Response Schema (`object`)

id
(Optional, integer) The ID of the Network Tunnel Group.
name
(Optional, string) The name of the Network Tunnel Group. A Network Tunnel Group name is a sequence of 1–50 characters. The name field cannot have any special characters other than spaces and hyphens.
organizationId
(Optional, integer) The ID of the organization.
deviceType
(Optional, string) The type of device that establishes the network tunnel. The default value is other.
region
(Optional, string) The name of the region that is used to get the primary and secondary data centers for the Hubs.
status
(Optional, string) The status of the Network Tunnel Group.
hubs
(Optional, array (object)) The list of Hubs for a Network Tunnel Group. Only one Hub is the primary data center.
- id
  (Optional, integer) The ID of the Hub.
- isPrimary
  (Optional, boolean) Specifies whether the Hub is a primary data center.
- datacenter
  (Optional, object)
- authId
  (Optional, string) An IP address or email used to authenticate the tunnel.
- status
  (Optional, object) The properties of a Hub for the Network Tunnel Group.
- tunnelsCount
  (Optional, integer) The number of tunnels in the hub.
routing
(Optional, oneOf) The routing information for the network tunnel.

If the routing type is nat, then the data field is empty. If the routing type is bgp, then data includes the asNumber field. If the routing type is static, then data includes the networkCIDRs field.
- oneOf-1
  - type
    (Required, string)
  - data
    (Required, object)
- oneOf-2
  - type
    (Required, string)
  - data
    (Required, object)
- oneOf-3
  - type
    (Required, string)
  - data
    (Required, object)
createdAt
(Optional, string) The date and time (timestamp) when the network tunnel group was created.
modifiedAt
(Optional, string) The date and time of the last update (timestamp) for the network tunnel group.

Response Sample

Click to view the sample response (200, OK)

Code Snippet

Copy{
    "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:50: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"
}

Get Network Tunnel Group

GET https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}

Description

Get a Network Tunnel Group in the organization.

Path Parameters

id
(Required, integer) The ID of the Network Tunnel Group.

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (`object`)

id
(Optional, integer) The ID of the Network Tunnel Group.
name
(Optional, string) The name of the Network Tunnel Group. A Network Tunnel Group name is a sequence of 1–50 characters. The name field cannot have any special characters other than spaces and hyphens.
organizationId
(Optional, integer) The ID of the organization.
deviceType
(Optional, string) The type of device that establishes the network tunnel. The default value is other.
region
(Optional, string) The name of the region that is used to get the primary and secondary data centers for the Hubs.
status
(Optional, string) The status of the Network Tunnel Group.
hubs
(Optional, array (object)) The list of Hubs for a Network Tunnel Group. Only one Hub is the primary data center.
- id
  (Optional, integer) The ID of the Hub.
- isPrimary
  (Optional, boolean) Specifies whether the Hub is a primary data center.
- datacenter
  (Optional, object)
- authId
  (Optional, string) An IP address or email used to authenticate the tunnel.
- status
  (Optional, object) The properties of a Hub for the Network Tunnel Group.
- tunnelsCount
  (Optional, integer) The number of tunnels in the hub.
routing
(Optional, oneOf) The routing information for the network tunnel.

If the routing type is nat, then the data field is empty. If the routing type is bgp, then data includes the asNumber field. If the routing type is static, then data includes the networkCIDRs field.
- oneOf-1
  - type
    (Required, string)
  - data
    (Required, object)
- oneOf-2
  - type
    (Required, string)
  - data
    (Required, object)
- oneOf-3
  - type
    (Required, string)
  - data
    (Required, object)
createdAt
(Optional, string) The date and time (timestamp) when the network tunnel group was created.
modifiedAt
(Optional, string) The date and time of the last update (timestamp) for the network tunnel group.

Response Sample

Click to view the sample response (200, OK)

Code Snippet

Copy{
    "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.umbrellagov.com",
            "status": {
                "status": "UP",
                "time": "2025-02-05T17:53:05Z"
            },
            "tunnelsCount": 5
        },
        {
            "id": 147852369,
            "isPrimary": false,
            "datacenter": {
                "name": "us-gov-east-1",
                "ip": "25.132.42.15"
            },
            "authId": "newyorkbranchtunnels123@123456-147852369.umbrellagov.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"
}

Update Network Tunnel Group

PATCH https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}

Description

Update a Network Tunnel Group in the organization.

Path Parameters

id
(Required, integer) The ID of the Network Tunnel Group.

Request Body Schema (`array`)

op
(Required, string) The operation that needs to be done. The only available operation is replace.
path
(Required, string) The path of the property that needs to be updated. Available paths are /name, /authIdPrefix, /passphrase, /region, and /routing.
value
(Required, oneOf)
- oneOf-1
  - (Optional, string) The new value for the property.
- oneOf-2
  - oneOf-1
    - type
      (Required, string)
    - data
      (Required, object)
  - oneOf-2
    - type
      (Required, string)
    - data
      (Required, object)
  - oneOf-3
    - type
      (Required, string)
    - data
      (Required, object)

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request PATCH --url 'https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (`object`)

id
(Optional, integer) The ID of the Network Tunnel Group.
name
(Optional, string) The name of the Network Tunnel Group. A Network Tunnel Group name is a sequence of 1–50 characters. The name field cannot have any special characters other than spaces and hyphens.
organizationId
(Optional, integer) The ID of the organization.
deviceType
(Optional, string) The type of device that establishes the network tunnel. The default value is other.
region
(Optional, string) The name of the region that is used to get the primary and secondary data centers for the Hubs.
status
(Optional, string) The status of the Network Tunnel Group.
hubs
(Optional, array (object)) The list of Hubs for a Network Tunnel Group. Only one Hub is the primary data center.
- id
  (Optional, integer) The ID of the Hub.
- isPrimary
  (Optional, boolean) Specifies whether the Hub is a primary data center.
- datacenter
  (Optional, object)
- authId
  (Optional, string) An IP address or email used to authenticate the tunnel.
- status
  (Optional, object) The properties of a Hub for the Network Tunnel Group.
- tunnelsCount
  (Optional, integer) The number of tunnels in the hub.
routing
(Optional, oneOf) The routing information for the network tunnel.

If the routing type is nat, then the data field is empty. If the routing type is bgp, then data includes the asNumber field. If the routing type is static, then data includes the networkCIDRs field.
- oneOf-1
  - type
    (Required, string)
  - data
    (Required, object)
- oneOf-2
  - type
    (Required, string)
  - data
    (Required, object)
- oneOf-3
  - type
    (Required, string)
  - data
    (Required, object)
createdAt
(Optional, string) The date and time (timestamp) when the network tunnel group was created.
modifiedAt
(Optional, string) The date and time of the last update (timestamp) for the network tunnel group.

Response Sample

Click to view the sample response (200, OK)

Code Snippet

Copy{
    "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.umbrellagov.com",
            "status": {
                "status": "UP",
                "time": "2025-02-05T17:53:05Z"
            },
            "tunnelsCount": 5
        },
        {
            "id": 147852369,
            "isPrimary": false,
            "datacenter": {
                "name": "us-gov-east-1",
                "ip": "25.132.42.15"
            },
            "authId": "newyorkbranchtunnels123@123456-147852369.umbrellagov.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"
}

Delete Network Tunnel Group

DELETE https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}

Description

Delete a Network Tunnel Group in the organization.

Path Parameters

id
(Required, integer) The ID of the Network Tunnel Group.

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request DELETE --url 'https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Sample

Code Snippet

Copy204 (No Content)

Get State of Network Tunnel Group

GET https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}/state

Description

Get the status information for the Network Tunnel Group in the organization. The maximum number of items in a hub's list of tunnel states (tunnelsStatus) is 10.

Path Parameters

id
(Required, integer) The ID of the Network Tunnel Group.

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}/state' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (`object`)

id
(Optional, integer) The ID of the Network Tunnel Group.
name
(Optional, string) The name of the Network Tunnel Group. A Network Tunnel Group name is a sequence of 1–50 characters. The name field cannot have any special characters other than spaces and hyphens.
organizationId
(Optional, integer) The ID of the organization.
status
(Optional, string) The status of the Network Tunnel Group.
hubs
(Optional, array (object)) The list of Hubs for a Network Tunnel Group. Only one Hub is the primary data center.
- id
  (Optional, integer) The ID of the Hub.
- isPrimary
  (Optional, boolean) Specifies whether the Hub is a primary data center.
- datacenter
  (Optional, object)
- status
  (Optional, object) The properties of a Hub for the Network Tunnel Group.
- tunnelsStatus
  (Optional, array (object)) The list of the states for the Network Tunnels. The maximum number of items in the list of tunnel states is 10.
  - time
    (Optional, string) The date and time (UTC time with milliseconds) when the state event record was generated.
  - status
    (Optional, string)
    The high-level status of the tunnel:
    - UP - The tunnel is active.
    - DOWN - The tunnel is inactive.
    - FAILED - The tunnel is in a failed state.
    - UNKNOWN - The current status is unknown and pending updated information.
  - dc
    (Optional, string) The domain name of the data center.
  - dcName
    (Optional, string) The name of the data center.
  - dcDesc
    (Optional, string) The city and country, or regional location of the data center.
  - ikeState
    (Optional, string)
    IKE SA State:
    - CREATED
    - CONNECTING
    - ESTABLISHED
    - PASSIVE
    - REKEYING
    - REKEYED
    - DELETING
    - DESTROYING
  - ipsecState
    (Optional, string)
    IPsec state:
    - CREATED
    - ROUTED
    - INSTALLING
    - INSTALLED
    - UPDATING
    - REKEYING
    - REKEYED
    - RETRYING
    - DELETING
    - DELETED
    - DESTROYING
  - peerId
    (Optional, string) The IKE ID of the remote peer.
  - peerIp
    (Optional, string) The IP address of the remote peer.
  - peerPort
    (Optional, string) The port of the remote peer.
  - localIp
    (Optional, string) The public IP address assigned to an endpoint device (for example: ISR, Viptela).
  - localPort
    (Optional, string) The port on the device.
  - ike
    (Optional, object) The IKE session state of the Network Tunnel.
  - ipsec
    (Optional, object) The IPsec session state and configuration information for the network tunnel.
  - data
    (Optional, object) The properties of the state of the tunnel.
  - routingStats
    (Optional, object) The routing statistics for a peer (tunnel).

Response Sample

Click to view the sample response (200, OK)

Code Snippet

Copy{
    "id": 4561237892,
    "name": "New York Branch Tunnels",
    "organizationId": 123456,
    "status": "warning",
    "hubs": [
        {
            "id": 987654321,
            "isPrimary": true,
            "datacenter": {
                "name": "us-gov-east-1"
            },
            "status": {
                "status": "UP",
                "time": "2023-06-30T16:07:07.222Z"
            },
            "tunnelsStatus": [
                {
                    "time": "2023-06-30T16:07:07.222Z",
                    "status": "UP",
                    "dc": "chi1.edc",
                    "dcName": "Equinix Chicago",
                    "dcDesc": "Chicago, Illinois - US",
                    "ikeState": "ESTABLISHED",
                    "ipsecState": "INSTALLED",
                    "peerId": "123456789009876543211234",
                    "peerIp": "198.18.195.1",
                    "peerPort": "4500",
                    "localIp": "198.25.43.19",
                    "localPort": "2456",
                    "ike": {
                        "age": "6194",
                        "dhGroup": "MODP_2048",
                        "prfAlgo": "PRF_HMAC_SHA1",
                        "encAlgo": "AES_CBC",
                        "initiatorSpi": "cf065c564a511834",
                        "responderSpi": "a3cd5c8533c80069"
                    },
                    "ipsec": {
                        "age": "6194",
                        "integrityAlgo": "HMAC_SHA1_96",
                        "encAlgo": "NULL",
                        "encKeySize": "128",
                        "spiIn": "c6ef7503",
                        "spiOut": "00010102",
                        "peerSelectors": [
                            "0.0.0.0/0\""
                        ]
                    },
                    "data": {
                        "packetsIn": "10",
                        "bytesIn": "1000",
                        "idleTimeIn": "100",
                        "packetsOut": "10",
                        "bytesOut": "1000",
                        "idleTimeOut": "100",
                        "initialized": "2023-06-30T16:07:01.245623734Z"
                    },
                    "routingStats": {
                        "clientRouteStats": {
                            "isClipped": false,
                            "stats": [
                                {
                                    "cidr": "25.10.10.24/32",
                                    "origin": "bgp",
                                    "priority": 1
                                }
                            ]
                        },
                        "cloudRouteStats": {
                            "isClipped": false,
                            "stats": [
                                {
                                    "cidr": "ff22::/120",
                                    "origin": "bgp",
                                    "priority": 1
                                },
                                {
                                    "cidr": "11.0.0.0/16",
                                    "origin": "bgp",
                                    "priority": 2
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ]
}

Get Peers States for Network Tunnel Group and Hub

GET https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}/peers

Description

Get the state of all peers (tunnels) within an organization's Network Tunnel Group and Hub.

Path Parameters

id
(Required, integer) The ID of the Network Tunnel Group.

Query Parameters

limit
(Optional, integer) An integer that represents the number of records to return in the response. The default value is 10.
offset
(Optional, integer) An integer that represents the place to start reading in the collection. When the offset is 0, the first page is returned from the collection. If the limit is 10, the offset for the next page is 10. The default value is 0.
sortBy
(Optional, string) Specify the field that will be used to sort the items from the collection in the response.
sortOrder
(Optional, string) Specify the sort order (ascending or descending) for the items in the response.

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}/peers' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (`array`)

time
(Optional, string) The date and time (UTC time with milliseconds) when the state event record was generated.
status
(Optional, string)
The high-level status of the tunnel:
- UP - The tunnel is active.
- DOWN - The tunnel is inactive.
- FAILED - The tunnel is in a failed state.
- UNKNOWN - The current status is unknown and pending updated information.
dc
(Optional, string) The domain name of the data center.
dcName
(Optional, string) The name of the data center.
dcDesc
(Optional, string) The city and country, or regional location of the data center.
ikeState
(Optional, string)
IKE SA State:
- CREATED
- CONNECTING
- ESTABLISHED
- PASSIVE
- REKEYING
- REKEYED
- DELETING
- DESTROYING
ipsecState
(Optional, string)
IPsec state:
- CREATED
- ROUTED
- INSTALLING
- INSTALLED
- UPDATING
- REKEYING
- REKEYED
- RETRYING
- DELETING
- DELETED
- DESTROYING
peerId
(Optional, string) The IKE ID of the remote peer.
peerIp
(Optional, string) The IP address of the remote peer.
peerPort
(Optional, string) The port of the remote peer.
localIp
(Optional, string) The public IP address assigned to an endpoint device (for example: ISR, Viptela).
localPort
(Optional, string) The port on the device.
ike
(Optional, object) The IKE session state of the Network Tunnel.

age
(Optional, string) Established state age in seconds.
dhGroup
(Optional, string) IKE Diffie-Hellman group.
prfAlgo
(Optional, string) IKE pseudo random function.
encAlgo
(Optional, string) IKE encryption algorithm.
initiatorSpi
(Optional, string) Hex encoded initiator SPI / cookie.
responderSpi
(Optional, string) Hex encoded responder SPI / cookie.

ipsec
(Optional, object) The IPsec session state and configuration information for the network tunnel.

age
(Optional, string) The installed state age in seconds.
integrityAlgo
(Optional, string) The ESP or AH integrity algorithm name.
encAlgo
(Optional, string) The ESP encryption algorithm name.
encKeySize
(Optional, string) The ESP encryption key size (optional field, not available with NULL encryption).
spiIn
(Optional, string) The Hex encoded inbound SPI.
spiOut
(Optional, string) The Hex encoded outbound SPI.
peerSelectors
(Optional, array (string)) The peer traffic selectors.

data
(Optional, object) The properties of the state of the tunnel.

packetsIn
(Optional, string) The number of processed input packets (tunnel ingress).
bytesIn
(Optional, string) The number of processed input bytes (tunnel ingress).
idleTimeIn
(Optional, string) The seconds since the last inbound packet (the time that the tunnel is idle).
packetsOut
(Optional, string) The number of processed output packets (tunnel egress).
bytesOut
(Optional, string) The number of processed output bytes (tunnel egress).
idleTimeOut
(Optional, string) The seconds since the last outbound packet (the time that the tunnel is idle).
initialized
(Optional, string) The time when the packet and byte counters were initialized to 0.

routingStats
(Optional, object) The routing statistics for a peer (tunnel).

clientRouteStats
(Optional, object) The properties of the client routing statistics.

isClipped
(Optional, boolean) Indicates whether the routing statistics for the client route are truncated.
stats
(Optional, array (object)) The list of the client routing statistics.
- cidr
  (Optional, string) The client routing CIDR address.
- origin
  (Optional, string) The origin of the client routing.
- priority
  (Optional, integer) The priority of the client routing.

cloudRouteStats
(Optional, object) The properites of the cloud routing statistics.

isClipped
(Optional, boolean) Indicates whether cloud route stats array has been truncated
stats
(Optional, array (object)) The list of the cloud routing statistics.
- cidr
  (Optional, string) The cloud routing CIDR address.
- origin
  (Optional, string) The origin of the cloud routing.
- priority
  (Optional, integer) The priority of the cloud routing.

Get Tunnel State for Network Tunnel Group and Hub

GET https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}/networktunnelhubs/{hub_id}/peers/{peer_id}/state

Description

Get the state of a peer (tunnel) within an organization's Network Tunnel Group and Hub.

Path Parameters

id
(Required, integer) The ID of the Network Tunnel Group.
hub_id
(Required, integer) The ID of the Network Tunnel Hub.
peer_id
(Required, integer) The ID of the peer (tunnel).

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/deployments/v2/networktunnelgroups/{id}/networktunnelhubs/{hub_id}/peers/{peer_id}/state' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (`object`)

time
(Optional, string) The date and time (UTC time with milliseconds) when the state event record was generated.
status
(Optional, string)
The high-level status of the tunnel:
- UP - The tunnel is active.
- DOWN - The tunnel is inactive.
- FAILED - The tunnel is in a failed state.
- UNKNOWN - The current status is unknown and pending updated information.
dc
(Optional, string) The domain name of the data center.
dcName
(Optional, string) The name of the data center.
dcDesc
(Optional, string) The city and country, or regional location of the data center.
ikeState
(Optional, string)
IKE SA State:
- CREATED
- CONNECTING
- ESTABLISHED
- PASSIVE
- REKEYING
- REKEYED
- DELETING
- DESTROYING
ipsecState
(Optional, string)
IPsec state:
- CREATED
- ROUTED
- INSTALLING
- INSTALLED
- UPDATING
- REKEYING
- REKEYED
- RETRYING
- DELETING
- DELETED
- DESTROYING
peerId
(Optional, string) The IKE ID of the remote peer.
peerIp
(Optional, string) The IP address of the remote peer.
peerPort
(Optional, string) The port of the remote peer.
localIp
(Optional, string) The public IP address assigned to an endpoint device (for example: ISR, Viptela).
localPort
(Optional, string) The port on the device.
ike
(Optional, object) The IKE session state of the Network Tunnel.

age
(Optional, string) Established state age in seconds.
dhGroup
(Optional, string) IKE Diffie-Hellman group.
prfAlgo
(Optional, string) IKE pseudo random function.
encAlgo
(Optional, string) IKE encryption algorithm.
initiatorSpi
(Optional, string) Hex encoded initiator SPI / cookie.
responderSpi
(Optional, string) Hex encoded responder SPI / cookie.

ipsec
(Optional, object) The IPsec session state and configuration information for the network tunnel.

age
(Optional, string) The installed state age in seconds.
integrityAlgo
(Optional, string) The ESP or AH integrity algorithm name.
encAlgo
(Optional, string) The ESP encryption algorithm name.
encKeySize
(Optional, string) The ESP encryption key size (optional field, not available with NULL encryption).
spiIn
(Optional, string) The Hex encoded inbound SPI.
spiOut
(Optional, string) The Hex encoded outbound SPI.
peerSelectors
(Optional, array (string)) The peer traffic selectors.

data
(Optional, object) The properties of the state of the tunnel.

packetsIn
(Optional, string) The number of processed input packets (tunnel ingress).
bytesIn
(Optional, string) The number of processed input bytes (tunnel ingress).
idleTimeIn
(Optional, string) The seconds since the last inbound packet (the time that the tunnel is idle).
packetsOut
(Optional, string) The number of processed output packets (tunnel egress).
bytesOut
(Optional, string) The number of processed output bytes (tunnel egress).
idleTimeOut
(Optional, string) The seconds since the last outbound packet (the time that the tunnel is idle).
initialized
(Optional, string) The time when the packet and byte counters were initialized to 0.

routingStats
(Optional, object) The routing statistics for a peer (tunnel).

clientRouteStats
(Optional, object) The properties of the client routing statistics.

isClipped
(Optional, boolean) Indicates whether the routing statistics for the client route are truncated.
stats
(Optional, array (object)) The list of the client routing statistics.
- cidr
  (Optional, string) The client routing CIDR address.
- origin
  (Optional, string) The origin of the client routing.
- priority
  (Optional, integer) The priority of the client routing.

cloudRouteStats
(Optional, object) The properites of the cloud routing statistics.

isClipped
(Optional, boolean) Indicates whether cloud route stats array has been truncated
stats
(Optional, array (object)) The list of the cloud routing statistics.
- cidr
  (Optional, string) The cloud routing CIDR address.
- origin
  (Optional, string) The origin of the cloud routing.
- priority
  (Optional, integer) The priority of the cloud routing.

List State of Network Tunnel Groups

GET https://api.umbrellagov.com/deployments/v2/networktunnelgroupsstate

Description

Get the state for each Network Tunnel Group in the organization. The maximum number of items in a hub's list of tunnel states (tunnelsStatus) is 10.

Query Parameters

offset
(Optional, integer) An integer that represents the place to start reading in the collection. When the offset is 0, the first page is returned from the collection. If the limit is 10, the offset for the next page is 10. The default value is 0.
limit
(Optional, integer) An integer that represents the number of records to return in the response.
sortBy
(Optional, string) Specify the field that will be used to sort the items from the collection in the response.
sortOrder
(Optional, string) Specify the sort order (ascending or descending) for the items in the response.

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/deployments/v2/networktunnelgroupsstate' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (`object`)

offset
(Optional, integer) An integer that represents the place to start reading in the collection.
limit
(Optional, integer) The number of items returned in the response.
total
(Optional, integer) The total number of items read from the collection.
data
(Optional, array (object)) The list of the Network Tunnel Groups in the organization.
- id
  (Optional, integer) The ID of the Network Tunnel Group.
- name
  (Optional, string) The name of the Network Tunnel Group. A Network Tunnel Group name is a sequence of 1–50 characters. The name field cannot have any special characters other than spaces and hyphens.
- organizationId
  (Optional, integer) The ID of the organization.
- status
  (Optional, string) The status of the Network Tunnel Group.
- hubs
  (Optional, array (object)) The list of Hubs for a Network Tunnel Group. Only one Hub is the primary data center.
  - id
    (Optional, integer) The ID of the Hub.
  - isPrimary
    (Optional, boolean) Specifies whether the Hub is a primary data center.
  - datacenter
    (Optional, object)
  - status
    (Optional, object) The properties of a Hub for the Network Tunnel Group.
  - tunnelsStatus
    (Optional, array (object)) The list of the states for the Network Tunnels. The maximum number of items in the list of tunnel states is 10.
    - time
      (Optional, string) The date and time (UTC time with milliseconds) when the state event record was generated.
    - status
      (Optional, string)
      The high-level status of the tunnel:
      - UP - The tunnel is active.
      - DOWN - The tunnel is inactive.
      - FAILED - The tunnel is in a failed state.
      - UNKNOWN - The current status is unknown and pending updated information.
    - dc
      (Optional, string) The domain name of the data center.
    - dcName
      (Optional, string) The name of the data center.
    - dcDesc
      (Optional, string) The city and country, or regional location of the data center.
    - ikeState
      (Optional, string)
      IKE SA State:
      - CREATED
      - CONNECTING
      - ESTABLISHED
      - PASSIVE
      - REKEYING
      - REKEYED
      - DELETING
      - DESTROYING
    - ipsecState
      (Optional, string)
      IPsec state:
      - CREATED
      - ROUTED
      - INSTALLING
      - INSTALLED
      - UPDATING
      - REKEYING
      - REKEYED
      - RETRYING
      - DELETING
      - DELETED
      - DESTROYING
    - peerId
      (Optional, string) The IKE ID of the remote peer.
    - peerIp
      (Optional, string) The IP address of the remote peer.
    - peerPort
      (Optional, string) The port of the remote peer.
    - localIp
      (Optional, string) The public IP address assigned to an endpoint device (for example: ISR, Viptela).
    - localPort
      (Optional, string) The port on the device.
    - ike
      (Optional, object) The IKE session state of the Network Tunnel.
    - ipsec
      (Optional, object) The IPsec session state and configuration information for the network tunnel.
    - data
      (Optional, object) The properties of the state of the tunnel.
    - routingStats
      (Optional, object) The routing statistics for a peer (tunnel).

List Regions for Network Tunnel Groups

GET https://api.umbrellagov.com/deployments/v2/regions

Description

List the available regions for the Network Tunnel Groups.

Query Parameters

filters
(Optional, object)
Filter the regions by one or more properties: peerIP or latitude and longitude.
- peerIP - List the regions in ascending order based on the distance of the regions to the location of the given peer IP. You can only set a public IP for peerIP. If latitude and longitude are provided, peerIP is ignored.
- latitude and longitude - List the regions in ascending order based on the distance of the regions from the provided coordinates. When included with a request, set both latitude and longitude.
Specify the filters in the JSON format.

Examples:
Code Snippet
Code Snippet - 1
Copy{ "peerIP": "25.123.22.10" }
Copy{ "latitude": "39.0299604", "longitude": "39.0299604" }

Request Sample

Code Snippet

Copy
curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/deployments/v2/regions' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Response Schema (`object`)

regions
(Optional, array (object)) The list of regions for the Network Tunnel Groups.
- name
  (Required, string) The name of a region.
- region
  (Required, string) The ID of a region.
- description
  (Required, string) The country and location of a region.
- continent
  (Required, string) The continent where the region is located.
bgp
(Optional, object)

asNumber
(Optional, string) The BGP autonomous system (AS) number.
peerIPs
(Optional, array (string)) The list of BGP peer IP addresses.
peerRange
(Optional, string) The range of BGP peer addresses.

Response Sample

Click to view the sample response (200, OK)

Code Snippet

Copy{
    "regions": [
        {
            "name": "US East 1",
            "region": "us-gov-east-1",
            "description": "US East (N. Virginia)",
            "continent": "North America"
        }
    ],
    "bgp": {
        "asNumber": "64512",
        "peerIPs": [
            "169.254.0.9",
            "169.254.0.5"
        ],
        "peerRange": "169.254.0.0/24"
    }
}

Network Tunnel Groups and Regions

List Network Tunnel Groups

Description

Query Parameters

Request Sample

Response Schema (object)

Response Sample

Create Network Tunnel Group

Description

Request Body Schema (object)

Request Sample

Response Schema (object)

Response Sample

Get Network Tunnel Group

Description

Path Parameters

Request Sample

Response Schema (object)

Response Sample

Update Network Tunnel Group

Description

Path Parameters

Request Body Schema (array)

Request Sample

Response Schema (object)

Response Sample

Delete Network Tunnel Group

Description

Path Parameters

Request Sample

Response Sample

Get State of Network Tunnel Group

Description

Path Parameters

Request Sample

Response Schema (object)

Response Sample

Get Peers States for Network Tunnel Group and Hub

Description

Path Parameters

Query Parameters

Request Sample

Response Schema (array)

Get Tunnel State for Network Tunnel Group and Hub

Description

Path Parameters

Request Sample

Response Schema (object)

List State of Network Tunnel Groups

Description

Query Parameters

Request Sample

Response Schema (object)

List Regions for Network Tunnel Groups

Description

Query Parameters

Request Sample

Response Schema (object)

Response Sample

Response Schema (`object`)

Request Body Schema (`object`)

Response Schema (`object`)

Response Schema (`object`)

Request Body Schema (`array`)

Response Schema (`object`)

Response Schema (`object`)

Response Schema (`array`)

Response Schema (`object`)

Response Schema (`object`)

Response Schema (`object`)