15.2 Cisco Catalyst SD-WAN Manager (vManage) REST APIs and Device Interaction

Cisco Catalyst SD-WAN Manager (vManage) REST APIs and Device Interaction

In modern Software-Defined Wide Area Network (SD-WAN) architectures, network control, management, and data forwarding are strictly decoupled. Cisco Catalyst SD-WAN Manager (formerly vManage) serves as the centralized network management system (NMS) and single pane of glass for the entire SD-WAN fabric. Operating in the management plane alongside vSmart controllers (control plane), vBond orchestrators (orchestration plane), and WAN Edge routers (data plane), SD-WAN Manager provides unified operational dashboards, real-time path telemetry, centralized policy definition, and automated zero-touch provisioning. Network engineers interact programmatically with SD-WAN Manager through its extensive REST API suite to automate Day-0 onboarding, Day-1 template configuration, and Day-2 health auditing across enterprise WAN transports.

+-------------------------------------------------------------------------+
|               Cisco Catalyst SD-WAN Manager Architecture                |
+-------------------------------------------------------------------------+
|                                                                         |
|   +-----------------------------------------------------------------+   |
|   |           Cisco Catalyst SD-WAN Manager (Management Plane)      |   |
|   | - Centralized GUI Dashboard                                     |   |
|   | - REST API Gateway: /dataservice/...                            |   |
|   | - Configuration Database, Template Engine, Alarm Aggregator     |   |
|   +-----------------------------------------------------------------+   |
|                 |                                   |                   |
|       Session & CSRF Auth                 NETCONF / OMP Telemetry       |
|                 |                                   |                   |
|                 v                                   v                   |
|   +---------------------------+       +-----------------------------+   |
|   |   Orchestration Plane     |       |        Control Plane        |   |
|   |   Catalyst SD-WAN Validator|       |   Catalyst SD-WAN Controller|   |
|   |   (vBond Orchestrator)    |       |   (vSmart Controller)       |   |
|   +---------------------------+       +-----------------------------+   |
|                 |                                   |                   |
|                 +-----------------+-----------------+                   |
|                                   |                                     |
|                                   v                                     |
|   +-----------------------------------------------------------------+   |
|   |                Data Forwarding Plane (WAN Edge Routers)         |   |
|   |   Catalyst 8300 / 8500 Edge, ASR 1000, ISR 4000, vEdge Cloud    |   |
|   |   IPsec Data Tunnels monitored continuously via BFD sessions    |   |
|   +-----------------------------------------------------------------+   |
+-------------------------------------------------------------------------+

SD-WAN Manager REST API Architecture and Namespace

All programmatic interactions with Catalyst SD-WAN Manager are exposed under the /dataservice root namespace over HTTPS (typically on TCP port 443 or port 8443 depending on deployment configuration). Unlike simple stateless APIs, SD-WAN Manager functions as a rich web application with stateful session management, granular role-based access control (RBAC), and multi-tenant segmentation capabilities.

The /dataservice namespace organizes API resources into distinct operational domains:

• Device and System Inventory (/dataservice/device): Enumerates all WAN Edge routers, vSmart controllers, and vBond orchestrators participating in the fabric, reporting reachability, hardware models, software versions, and chassis UUIDs.
• Operational Monitoring (/dataservice/device/...): Surfaces live telemetry from data plane nodes, including Bidirectional Forwarding Detection (BFD) tunnel health, OMP route tables, hardware environmentals, and control connections.
• Alarms and Events (/dataservice/alarms): Aggregates critical, major, and minor operational alarms across transport circuits, BGP peerings, and hardware components.
• Configuration and Templates (/dataservice/template/...): Creates, updates, and attaches feature templates and device CLI templates to physical and virtual routers.

Multi-Stage Authentication: Session Cookies and CSRF Protection

Because Catalyst SD-WAN Manager hosts critical state-modifying configuration workflows, it implements a multi-stage authentication handshake that combines HTTP session cookies with Cross-Site Request Forgery (CSRF) protection tokens. Automation clients cannot execute write operations using standard HTTP Basic Authentication alone.

+-------------------------------------------------------------------------+
|          SD-WAN Manager Authentication & Request Handshake              |
+-------------------------------------------------------------------------+
                                                                           
  [ Automation Client ]                           [ SD-WAN Manager ]       
           |                                               |               
           | 1. POST /j_security_check                     |               
           |    Body: j_username=admin&j_password=***      |               
           | --------------------------------------------> |               
           |                                               |               
           | 2. HTTP 200 OK / 302 Found                    |               
           |    Set-Cookie: JSESSIONID=abc123xyz           |               
           | <-------------------------------------------- |               
           |                                               |               
           | 3. GET /dataservice/client/token              |               
           |    Cookie: JSESSIONID=abc123xyz               |               
           | --------------------------------------------> |               
           |                                               |               
           | 4. HTTP 200 OK                                |               
           |    Body: "csrf-token-string-456"              |               
           | <-------------------------------------------- |               
           |                                               |               
           | 5. Modifying POST /dataservice/template/...   |               
           |    Cookie: JSESSIONID=abc123xyz               |               
           |    Header: X-XSRF-TOKEN: csrf-token-string-456|               
           | --------------------------------------------> |               
           |                                               |               
           | 6. HTTP 200 OK + Execution Result             |               
           | <-------------------------------------------- |               

The Three-Step Authentication Sequence

Step 1: Establish Authenticated Session (/j_security_check)

The client issues an HTTP POST request to the legacy Java security endpoint /j_security_check. The request body must be encoded as application/x-www-form-urlencoded containing the keys j_username and j_password:

POST /j_security_check HTTP/1.1
Host: vmanage.example.com:8443
Content-Type: application/x-www-form-urlencoded

j_username=admin&j_password=CiscoSDWAN123!

Upon successful verification, SD-WAN Manager issues an HTTP 200 OK (or redirects via 302 Found) and returns a session cookie in the Set-Cookie response header:

Set-Cookie: JSESSIONID=4A9B1C2D3E4F5A6B7C8D9E0F1A2B3C4D; Path=/; Secure; HttpOnly

This JSESSIONID cookie must be stored and passed in the Cookie header on all subsequent requests.

Step 2: Acquire CSRF Token (/dataservice/client/token)

To protect state-changing endpoints from CSRF exploits, SD-WAN Manager requires a unique cryptographic token for any operation that creates, updates, or deletes configuration. The client submits an HTTP GET request to /dataservice/client/token, presenting the established session cookie:

GET /dataservice/client/token HTTP/1.1
Host: vmanage.example.com:8443
Cookie: JSESSIONID=4A9B1C2D3E4F5A6B7C8D9E0F1A2B3C4D

The server returns the raw token string in the response body:

7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c

Step 3: Dispatch API Operations

Once authenticated, requests follow strict header requirements based on the HTTP method:

• Read-Only Operations (GET): Require only the session cookie (Cookie: JSESSIONID=...). The CSRF token is optional for GET operations.
• State-Modifying Operations (POST, PUT, DELETE): Strictly require both the session cookie (Cookie: JSESSIONID=...) AND the custom CSRF header (X-XSRF-TOKEN: <token>). If the CSRF token is absent or mismatched, SD-WAN Manager aborts the request immediately with an HTTP 403 Forbidden error.

Cisco Catalyst SD-WAN Manager Authentication Handshake

Core SD-WAN Manager API Endpoints

Enterprise network engineers leverage SD-WAN Manager APIs to monitor fabric health, track data tunnel performance, and orchestrate configuration policies:

1. Device Inventory (GET /dataservice/device)

The /dataservice/device endpoint returns a complete inventory of all managed entities registered in the SD-WAN fabric. Each entry in the JSON response contains essential operational metadata:

• system-ip: The unique loopback IPv4 identifier representing the node in the Overlay Management Protocol (OMP) topology.
• host-name: Configured system hostname (e.g., branch-edge-01).
• deviceModel: Platform hardware model (e.g., c8300-1n1s-4t2x, vedge-2000).
• reachability: Administrative reachability status (reachable or unreachable).
• status: Overall device state (e.g., normal, warning).
• personality: Role of the node in the fabric (vedge, vsmart, vbond).

2. Active Alarms (GET /dataservice/alarms)

The /dataservice/alarms endpoint aggregates real-time system alerts across all fabric nodes. Engineers can query active issues and filter by severity levels (Critical, Major, Minor):

• Fields returned include eventname, severity_level, component, entry_time, and acknowledged status. This endpoint is commonly used in automation monitoring scripts that feed corporate event-correlation engines like Splunk.

3. BFD Session Monitoring (GET /dataservice/device/bfd/sessions)

In Cisco Catalyst SD-WAN, WAN Edge routers establish IPsec data tunnels across each available transport circuit (MPLS, Internet, LTE) between transport locators (TLOCs). Bidirectional Forwarding Detection (BFD) runs continuously over every IPsec tunnel to detect path outages and measure transport performance.

Querying /dataservice/device/bfd/sessions?deviceId={system-ip} returns granular real-time tunnel telemetry:

• local-color and remote-color: Transport circuits forming the tunnel (e.g., mpls, biz-internet, public-internet).
• state: Current operational status of the tunnel (up or down).
• latency: Current round-trip latency measured in milliseconds.
• jitter: Current packet arrival variation in milliseconds.
• rx_pkts and tx_pkts: Total packets received and transmitted over the IPsec tunnel.
• loss: Percentage of dropped packets observed over the sampling interval.

4. Template Attachment (POST /dataservice/template/device/config/attachfeature)

Configuration management in Catalyst SD-WAN relies on standardized feature templates (defining individual protocol blocks like BGP, OSPF, NTP, and VPN interfaces) assembled into device templates. Pushing configurations to physical routers requires attaching the template along with a CSV or JSON payload containing device-specific variables (such as local interface IP addresses, BGP autonomous system numbers, and hostnames).

Core Catalyst SD-WAN Manager Endpoints Reference

Practical Python Automation Script Walkthrough

To handle session cookies seamlessly across multiple HTTP transactions, Python scripts should utilize requests.Session(). A Session object automatically retains cookies across all outgoing requests, simplifying the two-stage authentication sequence.

The following script logs into Catalyst SD-WAN Manager, acquires the CSRF token, queries the fabric device inventory to locate all WAN Edge routers, and retrieves real-time BFD tunnel performance metrics across their WAN transports.

import requests
import urllib3

# Suppress TLS verification warnings in development environments
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

VMANAGE_HOST = "198.51.100.10"
VMANAGE_PORT = 8443
USERNAME = "admin"
PASSWORD = "CiscoSDWAN123!"
BASE_URL = f"https://{VMANAGE_HOST}:{VMANAGE_PORT}"


def create_vmanage_session(base_url, username, password):
    """Establishes an authenticated requests.Session with JSESSIONID and X-XSRF-TOKEN."""
    session = requests.Session()
    # Step 1: Session Authentication via /j_security_check
    login_url = f"{base_url}/j_security_check"
    login_payload = {
        "j_username": username,
        "j_password": password
    }
    
    login_resp = session.post(login_url, data=login_payload, verify=False, timeout=15)
    login_resp.raise_for_status()
    
    # Verify that session cookie was acquired
    if "JSESSIONID" not in session.cookies:
        raise RuntimeError("Authentication failed: JSESSIONID cookie not returned.")
    
    print("Successfully authenticated session (JSESSIONID stored).")
    
    # Step 2: Acquire CSRF Token via /dataservice/client/token
    token_url = f"{base_url}/dataservice/client/token"
    token_resp = session.get(token_url, verify=False, timeout=10)
    
    if token_resp.status_code == 200:
        csrf_token = token_resp.text.strip()
        # Inject CSRF header into session for subsequent POST/PUT/DELETE calls
        session.headers.update({"X-XSRF-TOKEN": csrf_token})
        print("Successfully acquired X-XSRF-TOKEN.")
    else:
        print("Notice: CSRF token endpoint not required or returned non-200.")
        
    return session


def get_wan_edge_inventory(session, base_url):
    """Retrieves all reachable WAN Edge devices from /dataservice/device."""
    device_url = f"{base_url}/dataservice/device"
    response = session.get(device_url, verify=False, timeout=15)
    response.raise_for_status()
    
    all_devices = response.json().get("data", [])
    # Filter for WAN edge data plane nodes
    wan_edges = [
        d for d in all_devices 
        if d.get("personality") == "vedge" and d.get("reachability") == "reachable"
    ]
    return wan_edges


def audit_bfd_sessions(session, base_url, system_ip, hostname):
    """Audits live BFD tunnel performance for a given WAN Edge system IP."""
    bfd_url = f"{base_url}/dataservice/device/bfd/sessions"
    params = {"deviceId": system_ip}
    
    response = session.get(bfd_url, params=params, verify=False, timeout=15)
    response.raise_for_status()
    
    sessions = response.json().get("data", [])
    print(f"\n=== BFD Data Tunnels for {hostname} ({system_ip}) ===")
    print(f"Total Active Tunnels: {len(sessions)}")
    
    for s in sessions:
        dst_ip = s.get("dst-ip", "N/A")
        local_color = s.get("local-color", "N/A")
        remote_color = s.get("remote-color", "N/A")
        state = s.get("state", "down")
        latency = s.get("latency", "0")
        loss = s.get("loss", "0")
        
        status_indicator = "[OK]" if state == "up" else "[ALERT]"
        print(
            f"  {status_indicator} {local_color} -> {remote_color} "
            f"(Dst: {dst_ip}) | State: {state.upper()} | Latency: {latency}ms | Loss: {loss}%"
        )


if __name__ == "__main__":
    # Initialize authenticated session
    vmanage_session = create_vmanage_session(BASE_URL, USERNAME, PASSWORD)
    
    # Query WAN Edge Inventory
    edge_routers = get_wan_edge_inventory(vmanage_session, BASE_URL)
    print(f"Discovered {len(edge_routers)} active WAN Edge routers.")
    
    # Audit BFD Tunnels for each discovered Edge router
    for edge in edge_routers:
        sys_ip = edge.get("system-ip")
        host = edge.get("host-name", "Unnamed-Edge")
        audit_bfd_sessions(vmanage_session, BASE_URL, sys_ip, host)