Cisco Umbrella Network Tunnels API
Manage the network tunnels in the organization.
OpenAPI Specification
openapi: 3.0.1
info:
title: Cisco Umbrella Network Tunnels API
description: Manage the network tunnels in the organization.
version: 2.0.0
contact:
name: Cloud Security Developer Community
x-provenance:
method: harvested
authored_by: Cisco Umbrella
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
provider_published: true
source_host: pubhub.devnetcloud.com
note: 26 first-party OpenAPI 3.0 documents (256 operations) listed by Cisco's own docs-nav config and fetched anonymously.
Byte-identity reconfirmed 2026-08-19 by SHA-256 against the live source.
x-evidence:
- type: source
url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/umbrella-config.json
- type: source
url: https://developer.cisco.com/docs/cloud-security/
servers:
- url: https://api.umbrella.com/{basePath}
variables:
basePath:
default: deployments/v2
security:
- oauthFlow: []
tags:
- name: Data Center
- name: Organization Tunnel
- name: Debugging
- name: Umbrella
paths:
/datacenters:
get:
summary: List Data Centers
operationId: getDatacenters
security:
- oauthFlow:
- deployments.datacenters:read
description: 'List the information about the IPsec-enabled data centers.
The data center information includes the IP address and location details.'
tags:
- Data Center
- Umbrella
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: object
description: The information about the IPsec-enabled data centers.
properties:
continents:
type: array
description: The list of continents.
items:
type: object
description: The properties of the continent.
properties:
cities:
type: array
description: The list of cities.
items:
type: object
description: The properties of the city.
properties:
latitude:
type: string
description: The latitude of the city.
example: '52.354662'
longitude:
type: string
description: The longitude of the city.
example: '4.955532'
name:
type: string
description: The name of the city.
example: Amsterdam
dc:
type: string
description: The domain of the data center located in the city.
example: ams1.edc
range:
type: string
description: The IP or CIDR range of the data center that is located in the city.
example: 146.112.98.2/32
fqdn:
type: string
example: eu2-b.vpn.sig.umbrella.com
description: The FQDN associated with the city. Returns the FQDN if available.
name:
type: string
description: The name of the continent.
example: Europe
example:
continents:
- cities:
- latitude: '52.354662'
longitude: '4.955532'
name: Amsterdam
dc: ams1.edc
range: 146.112.98.2/32
fqdn: eu2-b.vpn.sig.umbrella.com
name: Europe
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/tunnels:
get:
summary: List Tunnels
operationId: listTunnels
description: List the tunnels for an organization.
security:
- oauthFlow:
- deployments.tunnels:read
tags:
- Organization Tunnel
- Umbrella
parameters:
- in: query
name: includeState
schema:
default: false
type: boolean
description: Specify whether to include the tunnel state information in the response.
required: false
- in: query
name: limit
description: The number of items to return in the collection. If not set, all tunnels are returned.
required: false
schema:
type: integer
- in: query
name: startKey
description: 'Specify where to start reading in the tunnel collection (`startKey` correlates to the first tunnel to
return).
If the `startKey` query parameter is not included in the API request, Umbrella reads the collection from the first
available tunnel.
When the API request includes the `limit` query parameter and you have more tunnels to read,
Umbrella returns the value of `startKey` for the next tunnel in the hypermedia Link header.'
required: false
schema:
type: string
- in: query
name: filters
description: "Filters the tunnel list by tunnel name, device type, service type, status, data center, or site origin\
\ ID.\nFor example:\n```\n{\n \"name\": \"test\",\n \"deviceType\": \"ISR\",\n \"serviceType\": \"SIG\",\n \"\
status\": \"UP\",\n \"dataCenter\": \"pao1.edc\",\n \"siteOriginId\": 123\n}\n```"
required: false
schema:
type: string
responses:
'200':
description: OKs
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
Total-Item-Count:
schema:
type: string
description: The total number of active, inactive, and unestablished tunnels in the organization.
example: '500'
Total-Distinct-DC-Count:
schema:
type: string
description: The number of distinct data centers in the organization.
example: '2'
Total-Active-Item-Count:
schema:
type: string
description: The total number of active tunnels in the organization.
example: '5'
Total-Inactive-Item-Count:
schema:
type: string
description: The total number of inactive tunnels in the organization.
example: '10'
Link:
schema:
type: string
description: 'The hypermedia links are formatted as a string. Use to provide parameters for pagination.
Only available if request limits the number of tunnels returned.
The link is a relative path. The `rel` value is always `next` (pagination moves forward).'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TunnelResourceObjectWithState'
example:
- id: 1122321
uri: /tunnels/1122321
name: Site01Tunnel
siteOriginId: 123456
client:
deviceType: ASA
authentication:
type: PSK
parameters:
id: admin@2561066-237952254-umbrella.com
modifiedAt: '2018-06-13T16:07:07.222Z'
transport:
protocol: IPSec
serviceType: SIG
networkCIDRs:
- 123.111.222.25/24
- 111.222.39.1/32
meta: {}
createdAt: '2018-06-13T16:07:07.222Z'
modifiedAt: '2018-06-13T16:07:07.222Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
post:
summary: Create Tunnel
operationId: addTunnel
description: Add a new tunnel to the organization.
security:
- oauthFlow:
- deployments.tunnels:write
tags:
- Organization Tunnel
- Umbrella
requestBody:
description: The tunnel to create.
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the tunnel.
siteOriginId:
type: integer
description: The site origin ID to associate with the tunnel.
example: 123456
deviceType:
type: string
description: The type of device where the tunnel originates. The default value is `other`.
enum:
- ASA
- FTD
- ISR
- Meraki MX
- Viptela cEdge
- Viptela vEdge
- other
serviceType:
$ref: '#/components/schemas/serviceType'
networkCIDRs:
$ref: '#/components/schemas/networkCIDRs'
transport:
type: object
properties:
protocol:
description: The tunnel transport protocol. The default tunnel transport protocol is IPSec.
type: string
enum:
- IPSec
example: IPSec
authentication:
type: object
properties:
type:
type: string
description: The authentication method. The default is pre-shared key (PSK).
enum:
- PSK
parameters:
type: object
properties:
idPrefix:
type: string
description: 'A human-readable ID for the tunnel, used to generate the ID portion of the Pre-Shared
Key.
If omitted, the ID is generated and provided in response. Tunnels with a device type of ASA
must provide an IP address string for this field. Tunnels with a device type of ''other''
may use either an IP address or a human-readable string. PSK IDs are not automatically generated
for ASA devices.'
secret:
type: string
description: 'The secret portion of a Pre-Shared Key (PSK).
If omitted, a secret is generated and provided in the response.
Secrets are a sequence of 16 to 64 characters, and contain at least one upper
and lowercase letter, one number, and no special characters.'
required:
- name
example:
name: Site01Tunnel
siteOriginId: 123456
serviceType: SIG
deviceType: ASA
networkCIDRs:
- 123.111.222.25/24
- 111.222.39.1/32
transport:
protocol: IPSec
authentication:
type: PSK
parameters:
idPrefix: prefix-string
secret: This123Secret
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/TunnelResourceObjectWithSecret'
example:
id: 1122321
uri: /tunnels/1122321
name: Site01Tunnel
siteOriginId: 123456
client:
deviceType: ASA
authentication:
type: PSK
parameters:
id: admin@2561066-237952254-umbrella.com
modifiedAt: '2018-06-13T16:07:07.222Z'
secret: This123Secret
transport:
protocol: IPSec
serviceType: SIG
networkCIDRs:
- 123.111.222.25/24
- 111.222.39.1/32
meta: {}
createdAt: '2018-06-13T16:07:07.222Z'
modifiedAt: '2018-06-13T16:07:07.222Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/tunnels/{id}:
get:
summary: Get Tunnel
operationId: getTunnel
description: Get a specific tunnel.
security:
- oauthFlow:
- deployments.tunnels:read
parameters:
- in: path
name: id
description: The ID of the tunnel.
required: true
schema:
type: integer
tags:
- Organization Tunnel
- Umbrella
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/TunnelResourceObject'
example:
id: 1122321
uri: /tunnels/1122321
name: Site01Tunnel
siteOriginId: 123456
client:
deviceType: ASA
authentication:
type: PSK
parameters:
id: admin@2561066-237952254-umbrella.com
modifiedAt: '2018-06-13T16:07:07.222Z'
transport:
protocol: IPSec
serviceType: SIG
networkCIDRs:
- 123.111.222.25/24
- 111.222.39.1/32
meta: {}
createdAt: '2018-06-13T16:07:07.222Z'
modifiedAt: '2018-06-13T16:07:07.222Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
put:
summary: Update Tunnel
operationId: updateTunnel
security:
- oauthFlow:
- deployments.tunnels:write
description: 'Update the `name`, `siteOriginId`, `networkCIDRs`, and client `deviceType` properties for a tunnel.
Updates to read-only attributes are ignored.'
tags:
- Organization Tunnel
- Umbrella
parameters:
- in: path
name: id
description: The ID of the tunnel.
required: true
schema:
type: integer
requestBody:
description: Provide a tunnel to update.
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: 'Display name for the tunnel. The tunnel name is required. The name can''t exceed 50 characters
in length and can not have any special characters other than spaces and hyphens.'
example: Site01Tunnel
siteOriginId:
type: integer
description: The site origin ID that is associated with the tunnel.
example: 123
networkCIDRs:
$ref: '#/components/schemas/networkCIDRs'
client:
type: object
description: The configuration metadata for the client.
properties:
deviceType:
type: string
description: The type of device from which the tunnel originates. The default value is `other`.
enum:
- ASA
- FTD
- ISR
- Meraki MX
- Viptela cEdge
- Viptela vEdge
- other
example: ASA
authentication:
type: object
description: The authentication context of the client.
properties:
type:
type: string
enum:
- PSK
example: PSK
readOnly: true
parameters:
type: object
properties:
id:
type: string
description: The PSK ID. If an IP address is used as the ID, the IP address is returned.
readOnly: true
example: admin@2561066-237952254-umbrella.com
modifiedAt:
$ref: '#/components/schemas/modifiedAt'
required:
- name
- client
example:
name: Site01Tunnel
siteOriginId: 123
networkCIDRs:
- 123.111.222.25/24
- 111.222.39.1/32
client:
deviceType: ASA
authentication:
type: PSK
parameters:
id: admin@2561066-237952254-umbrella.com
modifiedAt: '2018-06-13T16:07:07.222Z'
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/TunnelResourceObject'
example:
id: 1122321
uri: /tunnels/1122321
name: Site01Tunnel
siteOriginId: 123456
client:
deviceType: ASA
authentication:
type: PSK
parameters:
id: admin@2561066-237952254-umbrella.com
modifiedAt: '2018-06-13T16:07:07.222Z'
transport:
protocol: IPSec
serviceType: SIG
networkCIDRs:
- 123.111.222.25/24
- 111.222.39.1/32
meta: {}
createdAt: '2018-06-13T16:07:07.222Z'
modifiedAt: '2018-06-13T16:07:07.222Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
delete:
summary: Delete Tunnel
operationId: deleteTunnel
description: Delete a tunnel in the organization.
security:
- oauthFlow:
- deployments.tunnels:write
tags:
- Organization Tunnel
- Umbrella
parameters:
- in: path
name: id
description: The ID of the tunnel.
required: true
schema:
type: integer
requestBody:
description: Provide the tunnel to delete.
required: true
content:
application/json:
schema:
type: object
properties:
detachPolicies:
type: boolean
default: true
description: Specifies whether to detach associated policies from the tunnel.
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Tunnel deleted successfully
example:
message: Tunnel deleted successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/ServerError'
/tunnels/{id}/keys:
post:
summary: Update and Rotate Tunnel Credentials
description: Update and rotate the tunnel credentials.
tags:
- Organization Tunnel
- Umbrella
operationId: updateTunnelCredentials
security:
- oauthFlow:
- deployments.tunnels:write
parameters:
- in: path
name: id
description: The ID of the tunnel.
required: true
schema:
type: integer
requestBody:
description: 'The credentials and options to update and rotate the tunnel. Umbrella stores the
previous credentials for 24 hours unless stated.'
required: true
content:
application/json:
schema:
type: object
properties:
deprecateCurrentKeys:
type: boolean
default: false
description: 'Specifies whether to deprecate any existing credentials.
The 24-hour window does not apply.
Umbrella deletes the existing keys immediately. Set either both `idPrefix` and `secret` or `autoRotate`
to true. The default value is false.'
autoRotate:
type: boolean
description: 'Specifies whether to autogenerate keys.
The 24-hour window applies. Umbrella ignores any passed in credentials.'
psk:
type: object
properties:
idPrefix:
type: string
description: 'Required if autoRotate is set to false. To be concatenated with server-side parameters
to generate the ID for the pre-shared key (PSK). If the value of `idPrefix` matches the current `idPrefix`,
then 24-hour credential storage is disabled. If the tunnel uses an IP address as the PSK ID, format
the IP address as a string;
`autoRotate` is disabled.'
secret:
type: string
description: 'The secret aspect of a Pre-Shared Key. Optional, but either idPrefix OR idPrefix
and secret must be passed OR auto-Rotate set to true.
(16-64 characters, at least one upper and lowercase letter, one number, no special characters.)'
required:
- autoRotate
example:
deprecateCurrentKeys: true
autoRotate: true
psk:
idPrefix: prefix-string
secret: Secret123
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/TunnelResourceObjectWithSecret'
example:
id: 1122321
uri: /tunnels/1122321
name: Site01Tunnel
siteOriginId: 123456
client:
deviceType: ASA
authentication:
type: PSK
parameters:
id: admin@2561066-237952254-umbrella.com
modifiedAt: '2018-06-13T16:07:07.222Z'
secret: This123Secret
transport:
protocol: IPSec
serviceType: SIG
networkCIDRs:
- 123.111.222.25/24
- 111.222.39.1/32
meta: {}
createdAt: '2018-06-13T16:07:07.222Z'
modifiedAt: '2018-06-13T16:07:07.222Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/tunnels/{id}/policies:
get:
summary: List Policies for Tunnel
operationId: getTunnelPolicies
security:
- oauthFlow:
- deployments.tunnels:read
description: List the policies that include the network tunnel.
parameters:
- in: path
name: id
description: The ID of the tunnel.
required: true
schema:
type: integer
- in: query
schema:
type: string
enum:
- firewallrule
- web
name: type
description: Filter the list of policies to only include the specified type.
required: false
- in: query
schema:
type: integer
name: limit
description: The number of items to return in the collection.
required: false
- in: query
schema:
type: integer
name: page
description: The number of a page in the collection. Use with the limit parameter to implement pagination.
required: false
tags:
- Organization Tunnel
- Umbrella
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: array
description: Policies associated with a tunnel.
readOnly: true
items:
type: object
readOnly: true
properties:
id:
type: integer
description: The resource ID. Use the ID as reference for subsequent requests.
example: 1122321
type:
type: string
description: The type of policy.
enum:
- firewallrule
- web
name:
type: string
description: The name of the policy.
example: Test Firewall Rule (Block Application)
organizationId:
type: integer
description: The organization ID.
example: 33451234
priority:
type: integer
description: An integer that represents the position of the policy in the policy list.
example: 4
isDefault:
type: boolean
description: Indicates whether the policy is the default policy.
isAppliedDirectly:
type: boolean
description: 'True if the tunnel is applied directly to this policy, false if the policy
is configured to use all tunnels.'
createdAt:
type: string
description: The date and time (timestamp) when the tunnel was created.
format: date-time
example: '2018-06-13T16:07:07.222Z'
modifiedAt:
$ref: '#/components/schemas/modifiedAt'
uri:
type: string
description: Resource URI
example: /v2/tunnels/8765432/policies
example:
- id: 1122321
type: web
name: Test Firewall Rule (Block Application)
organizationId: 33451234
priority: 4
isDefault: true
isAppliedDirectly: true
createdAt: '2018-06-13T16:07:07.222Z'
modifiedAt: '2018-06-13T16:07:07.222Z'
uri: /v2/tunnels/8765432/policies
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/tunnelsState:
get:
tags:
- Debugging
- Umbrella
summary: List Tunnel State Information
operationId: getOrgTunnelState
security:
- oauthFlow:
- deployments.tunnels:read
description: List the tunnel state information.
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TunnelStateInformation'
example:
- tunnelId: '163367136'
status: UP
dc: chi1.edc
dcName: Equinix Chicago
dcDesc: Chicago, Illinois - US
ikeState: ESTABLISHED
ipsecState: INSTALLED
peerId: unique-value@1234567-234567812-umbrella.com
peerIp: 198.18.195.1
localIp: 198.25.43.19
peerPort: '4500'
ike:
age: '6194'
dhGroup: MODP_2048
prfAlgo: PRF_HMAC_SHA1
encAlgo: AES_CBC
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cisco-umbrella/refs/heads/main/openapi/cisco-umbrella-deployments-network-tunnels-openapi.yml