openapi: 3.2.0
info:
  title: Cisco Umbrella Network Tunnels Organization Tunnel 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: Organization Tunnel
paths:
  /tunnels:
    get:
      summary: List Tunnels
      operationId: listTunnels
      description: List the tunnels for an organization.
      security:
      - oauthFlow:
        - deployments.tunnels:read
      tags:
      - Organization Tunnel
      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
      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
      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
      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
      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
      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
      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'
components:
  headers:
    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'
    Content-Type:
      schema:
        type: string
      description: The MIME content type of the response body.
      example: application/json
  schemas:
    parametersWithSecret:
      type: object
      properties:
        id:
          type: string
          description: The PSK ID. If an IP address is used as the ID, the IP address is the value of this field.
          readOnly: true
          example: admin@2561066-237952254-umbrella.com
        modifiedAt:
          $ref: '#/components/schemas/modifiedAt'
        secret:
          $ref: '#/components/schemas/secretParameter'
    authentication:
      type: object
      description: The authentication context of the client.
      properties:
        type:
          type: string
          enum:
          - PSK
          example: PSK
          readOnly: true
        parameters:
          $ref: '#/components/schemas/parameters'
    ikeState:
      type: string
      readOnly: true
      description: "IKE SA State:\n  * CREATED\n  * CONNECTING\n  * ESTABLISHED\n  * PASSIVE\n  * REKEYING\n  * REKEYED\n  * DELETING\n  * DESTROYING\n"
      enum:
      - CREATED
      - CONNECTING
      - ESTABLISHED
      - PASSIVE
      - REKEYING
      - REKEYED
      - DELETING
      - DESTROYING
      example: ESTABLISHED
    secretParameter:
      type: string
      example: 123Secret
      description: The secret of the PSK credentials. Ensure that you save the secret. The secret is not provided at any other time.
    TunnelResourceObjectWithSecret:
      type: object
      description: The properties of the tunnel resource object.
      properties:
        id:
          type: integer
          readOnly: true
          description: The tunnel resource ID. Use this ID as a reference for subsequent requests.
          example: 1122321
        uri:
          type: string
          description: Resource URI
          readOnly: true
          example: /tunnels/1122321
        name:
          type: string
          description: 'Display the name of the tunnel. The tunnel name is required, cannot exceed 50 characters in length,

            and can''t 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: 123456
        client:
          $ref: '#/components/schemas/TunnelClientMetadataWithSecret'
        transport:
          type: object
          properties:
            protocol:
              description: The tunnel transport protocol. The default transport protocol is IPSec.
              type: string
              enum:
              - IPSec
              readOnly: true
              example: IPSec
        serviceType:
          $ref: '#/components/schemas/serviceType'
        networkCIDRs:
          $ref: '#/components/schemas/networkCIDRs'
        meta:
          type: object
          description: The metadata for the tunnel object, related to service internals.
          readOnly: true
        createdAt:
          type: string
          description: The date and time (timestamp) when the tunnel was created.
          format: date-time
          readOnly: true
          example: '2018-06-13T16:07:07.222Z'
        modifiedAt:
          $ref: '#/components/schemas/modifiedAt'
      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: secretkey123
        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'
    parameters:
      type: object
      properties:
        id:
          type: string
          description: The PSK ID. If an IP address is used as the ID, the IP address is the value of this field.
          readOnly: true
          example: admin@2561066-237952254-umbrella.com
        modifiedAt:
          $ref: '#/components/schemas/modifiedAt'
    serviceType:
      type: string
      description: The type of service to associate with the tunnel. The default value is `SIG`.
      enum:
      - SIG
      - Private Access
      example: SIG
    modifiedAt:
      type: string
      format: date-time
      readOnly: true
      example: '2018-06-13T16:07:07.222Z'
      description: The data and time (timestamp) when the tunnel was updated.
    authenticationWithSecret:
      type: object
      description: The authentication context of the client.
      properties:
        type:
          type: string
          enum:
          - PSK
          example: PSK
          readOnly: true
        parameters:
          $ref: '#/components/schemas/parametersWithSecret'
    TunnelResourceObject:
      type: object
      description: The tunnel resource object.
      properties:
        id:
          type: integer
          readOnly: true
          description: The tunnel resource ID, use this ID as reference for subsequent requests.
          example: 1122321
        uri:
          type: string
          description: Resource URI
          readOnly: true
          example: /tunnels/1122321
        name:
          type: string
          description: 'The display name of the tunnel. The tunnel name is required, cannot exceed 50 characters in length,

            and can''t have any special characters other than spaces and hyphens.'
          example: Site01Tunnel
        siteOriginId:
          type: integer
          description: The site origin ID, which is associated with the tunnel.
          example: 123456
        client:
          $ref: '#/components/schemas/TunnelClientMetadata'
        transport:
          type: object
          properties:
            protocol:
              description: The tunnel transport protocol. The default is IPSec.
              type: string
              enum:
              - IPSec
              readOnly: true
              example: IPSec
        serviceType:
          $ref: '#/components/schemas/serviceType'
        networkCIDRs:
          $ref: '#/components/schemas/networkCIDRs'
        meta:
          type: object
          description: Metadata for the tunnel object, relating to service internals.
          readOnly: true
        createdAt:
          type: string
          description: The time when the tunnel was created.
          format: date-time
          readOnly: true
          example: '2018-06-13T16:07:07.222Z'
        modifiedAt:
          $ref: '#/components/schemas/modifiedAt'
      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'
    TunnelResourceObjectWithState:
      type: object
      description: 'Get the information about the tunnel in the organization.

        To include the tunnel state information in the response, set the `includeState` request query parameter to `true`.'
      properties:
        id:
          type: integer
          readOnly: true
          description: The tunnel resource ID. Use this ID as a reference for subsequent requests.
          example: 1122321
        uri:
          type: string
          description: Resource URI
          readOnly: true
          example: /organization/2345432/tunnels/1122321
        name:
          type: string
          description: 'The display name of the tunnel. The tunnel name is required, cannot exceed 50 characters in length,

            and cannot have any special characters other than spaces and hyphens.'
          example: Site01Tunnel
        siteOriginId:
          type: integer
          description: Site Origin ID to associate with the tunnel
          example: 123456
        client:
          $ref: '#/components/schemas/TunnelClientMetadata'
        transport:
          type: object
          properties:
            protocol:
              description: The tunnel transport protocol. The default is IPSec.
              type: string
              enum:
              - IPSec
              readOnly: true
              example: IPSec
        serviceType:
          $ref: '#/components/schemas/serviceType'
        networkCIDRs:
          $ref: '#/components/schemas/networkCIDRs'
        meta:
          type: object
          description: The metadata for the tunnel object that relates to service internals.
          readOnly: true
          properties:
            state:
              title: tunnelState
              description: The tunnel state information.
              properties:
                tunnelId:
                  type: string
                  readOnly: true
                  description: The tunnel ID.
                  example: '163367136'
                status:
                  type: string
                  readOnly: true
                  description: 'The high-level tunnel status:

                    * up - the tunnel is active

                    * down - the tunnel is inactive

                    * failed - the tunnel is in a failed state

                    * unknown - the status is unknown and pending updated information

                    '
                  enum:
                  - UP
                  - DOWN
                  - FAILED
                  - UNKNOWN
                  example: UP
                dc:
                  type: string
                  readOnly: true
                  description: The domain name that is associate with the data center.
                  example: chi1.edc
                dcName:
                  type: string
                  readOnly: true
                  description: The name of the data center.
                  example: Equinix Chicago
                dcDesc:
                  type: string
                  readOnly: true
                  description: The city and country or region of the data center.
                  example: Chicago, Illinois - US
                ikeState:
                  $ref: '#/components/schemas/ikeState'
                ipsecState:
                  $ref: '#/components/schemas/ipsecState'
                peerId:
                  type: string
                  readOnly: true
                  description: The remote peer IKE ID.
                  example: unique-value@1234567-234567812-umbrella.com
                peerIp:
                  type: string
                  readOnly: true
                  description: The remote peer IP.
                  example: 198.18.195.1
                localIp:
                  type: string
                  readOnly: true
                  description: The public IP address, which is assigned to an endpoint device (ISR, Viptela).
                  example: 198.25.43.19
                peerPort:
                  type: string
                  readOnly: true
                  description: The port number of the remote peer.
                  example: '4500'
                ike:
                  title: tunnelIKEState
                  description: The tunnel IKE session state.
                  properties:
                    age:
                      type: string
                      readOnly: true
                      description: The age of the established state in seconds.
                      example: '6194'
                    dhGroup:
                      type: string
                      readOnly: true
                      description: The IKE Diffie-Hellman group.
                      example: MODP_2048
                    prfAlgo:
                      type: string
                      readOnly: true
                      description: The IKE pseudo random function.
                      example: PRF_HMAC_SHA1
                    encAlgo:
                      type: string
                      readOnly: true
                      description: The IKE encryption algorithm.
                      example: AES_CBC
                    initiatorSpi:
                      type: string
                      readOnly: true
                      description: The hex encoded initiator SPI or cookie.
                      example: cf065c564a511834
                    responderSpi:
                      type: string
                      readOnly: true
                      description: The hex encoded responder SPI or cookie.
                      example: a3cd5c8533c80069
                ipsec:
                  title: tunnelIPSecState
                  description: The tunnel IPsec session state.
                  properties:
                    age:
                      type: string
                      readOnly: true
                      description: The age of the installed state in seconds.
                      example: '6194'
                    integrityAlgo:
                      type: string
                      readOnly: true
                      description: The ESP or AH integrity algorithm name.
                      example: HMAC_SHA1_96
                    encAlgo:
                      type: string
                      readOnly: true
                      description: The ESP encryption algorithm name.
                      example: 'NULL'
                    encKeySize:
                      type: string
                      readOnly: true
                      description: The ESP encryption key size (optional field; not available with NULL encryption.
                      example: '128'
                    spiIn:
                      type: string
                      readOnly: true
                      description: The hex encoded inbound SPI.
                      example: c6ef7503
                    spiOut:
                      type: string
                      readOnly: true
                      description: The hex encoded outbound SPI.
                      example: '00010102'
                    peerSelectors:
                      type: array
                      readOnly: true
                      description: The peer traffic selectors.
                      items:
                        type: string
                        description: The selector expression.
                        example: 0.0.0.0/0
                data:
                  title: tunnelDataState
                  description: The state of the tunnel's data plane.
                  properties:
                    packetsIn:
                      type: string
                      readOnly: true
                      description: The number of processed input packets (tunnel ingress).
                      example: '10'
                    bytesIn:
                      type: string
                      readOnly: true
                      description: The number of processed input bytes (tunnel ingress).
                      example: '1000'
                    idleTimeIn:
                      type: string
                      readOnly: true
                      description: The idle time (seconds since last inbound packet).
                      example: '100'
                    packetsOut:
                      type: string
                      readOnly: true
                      description: The number of processed output packets (tunnel egress).
                      example: '10'
                    bytesOut:
                      type: string
                      readOnly: true
                      description: The number of processed output bytes (tunnel egress).
                      example: '1000'
                    idleTimeOut:
                      type: string
                      readOnly: true
                      description: The idle time (seconds since last outbound packet).
                      example: '100'
                    initialized:
                      type: string
                      readOnly: true
                      description: The time when packet and byte counters were initialized to 0.
                      example: '2023-10-19T22:15:12.765623734Z'
                modifiedAt:
                  type: string
                  readOnly: true
                  format: date-time
                  description: The date and time (UTC time with milliseconds) when the tunnel's state was last updated.
                  example: '2018-06-13T16:07:07.222Z'
        createdAt:
          type: string
          format: date-time
          description: The date and n time (UTC time with milliseconds) when the tunnel was created.
          readOnly: true
          example: '2018-06-13T16:07:07.222Z'
        modifiedAt:
          $ref: '#/components/schemas/modifiedAt'
    networkCIDRs:
      type: array
      description: 'Enter IPv4 ranges and CIDR addresses.

        If `serviceType` is SIG, add all public and private address ranges used internally

        by your organization. Overrides Umbrella''s default behavior,

        which allows traffic that is destined for RFC-1918 addresses to return through the tunnel.

        If `serviceType` is Private Access, this field is required.

        The 0.0.0.0/0 address range is not allowed.'
      items:
        type: string
        description: An IPv4 CIDR range.
        example: 111.222.39.1/32
      example:
      - 123.111.222.25/24
      - 111.222.39.1/32
    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
    TunnelClientMetadataWithSecret:
      type: object
      description: The tunnel client's configuration metadata including the client secret.
      properties:
        deviceType:
          $ref: '#/components/schemas/deviceType'
        authentication:
          $ref: '#/components/schemas/authenticationWithSecret'
    TunnelClientMetadata:
      type: object
      description: The tunnel client's configuration metadata.
      properties:
        deviceType:
          $ref: '#/components/schemas/deviceType'
        authentication:
          $ref: '#/components/schemas/authentication'
    ipsecState:
      type: string
      readOnly: true
      description: "IPSec/Child SA State:\n  * CREATED\n  * ROUTED\n  * INSTALLING\n  * INSTALLED\n  * UPDATING\n  * REKEYING\n  * REKEYED\n  * RETRYING\n  * DELETING\n  * DELETED\n  * DESTROYING\n"
      enum:
      - CREATED
      - ROUTED
      - INSTALLING
      - INSTALLED
      - UPDATING
      - REKEYING
      - REKEYED
      - RETRYING
      - DELETING
      - DELETED
      - DESTROYING
      example: INSTALLED
  responses:
    NotFound:
      description: Not Found
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            minProperties: 3
            required:
            - statusCode
            - error
            - txId
            properties:
              statusCode:
                type: integer
                example: 404
                description: HTTP status code
              error:
                type: string
                example: Not Found
                description: A brief description of the error
              txId:
                type: string
                example: 86e189a6-0124-47d3-a32c-25ff3f07deaf
                description: a unique hex number that can be used for debugging
    Unauthorized:
      description: Unauthorized
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            minProperties: 3
            required:
            - statusCode
            - error
            - txId
            properties:
              statusCode:
                type: integer
                example: 401
                description: HTTP status code
              error:
                type: string
                example: Unauthorized
                description: A brief description of the error
              txId:
                type: string
                example: 86e189a6-0124-47d3-a32c-25ff3f07deaf
                description: a unique hex number that can be used for debugging
    BadRequest:
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            minProperties: 3
            required:
            - statusCode
            - error
            - txId
            properties:
              statusCode:
                type: integer
                example: 400
                description: HTTP status code
              error:
                type: string
                example: Validation Error
                description: a brief description of the error
              txId:
                type: string
                example: 86e189a6-0124-47d3-a32c-25ff3f07deaf
                description: a unique hex number that can be used for debugging
              validationErrors:
                type: object
                properties:
                  someProperty:
                    type: string
                    example: must not be empty
                    description: the name of the property failing validation.
    ServerError:
      description: Internal Server Error
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            minProperties: 3
            required:
            - statusCode
            - error
            - txId
            properties:
              statusCode:
                type: integer
                example: 500
                description: HTTP status code
              error:
                type: string
                example: Internal Server Error
                description: a brief description of the error
              txId:
                type: string
                example: 86e189a6-0124-47d3-a32c-25ff3f07deaf
                description: a unique hex number that can be used for debugging
    Conflict:
      description: Conflict
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            description: 'Conflict - Unable to delete requested tunnel as it is attached

              to a policy and detachPolicies was not specified in the request.

              Check the response body for policies which this tunnel is attached to.'
            properties:
              error:
                type: string
                example: 'Umbrella cannot delete this tunnel as it is currently in use.

                  To delete this tunnel, remove it from all policies and deployments.'
              firewallRules:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      example: 123
                    name:
                      type: string
                      example: Example policy name
              dnsPolicies:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      example: 456
                    name:
                      type: string
                      example: Another example policy name
              internalNetworks:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: number
                      example: 789
                    label:
                      type: string
                      example: Yet another example policy name
    Forbidden:
      description: Forbidden
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            minProperties: 1
            required:
            - message
            properties:
              statusCode:
                type: integer
                example: 403
                description: HTTP status code
              message:
                type: string
                example: 'SIG is not enabled, please check with Cisco Support.

                  You have reached the maximum number of network tunnels for this organization.

                  To increase the limit, contact your administrator.

                  '
                description: Error message explaining the reason for failure
  securitySchemes:
    oauthFlow:
      type: oauth2
      description: client credential flow
      flows:
        clientCredentials:
          tokenUrl: https://api.umbrella.com/auth/v2/token
          scopes:
            deployments.tunnels:write: Write deployments tunnels
            deployments.tunnels:read: Read deployments tunnels
            deployments.datacenters:read: Read deployments datacenters
x-provenance:
  method: harvested
  first_party: true
  harvested: '2026-08-19'
  source: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/network-tunnels.yaml
  publisher: Cisco Systems, Inc. (Cisco DevNet Cloud Security docs)
x-evidence:
  fetched: '2026-08-19'
  url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/network-tunnels.yaml
  http_status: 200
  docs: https://developer.cisco.com/docs/cloud-security/