15.1 Cisco Catalyst Center Intent APIs and Authentication Workflows

Cisco Catalyst Center Intent APIs and Authentication Workflows

Modern enterprise campus environments require centralized, programmatic control to manage hundreds of switches, routers, and wireless access points without relying on error-prone per-device CLI sessions. Cisco Catalyst Center (formerly Cisco Digital Network Architecture Center, or DNA Center) serves as the foundational controller and analytics platform for enterprise intent-based networking. Rather than requiring network engineers to translate business requirements into device-specific syntax manually, Catalyst Center abstracts physical and virtual network elements behind a centralized programmatic control plane. This controller exposes a comprehensive suite of Representational State Transfer (REST) APIs that enable automated provisioning, dynamic policy enforcement, real-time telemetry extraction, and seamless integration with third-party enterprise IT systems.

+-------------------------------------------------------------------------+
|                 Cisco Catalyst Center REST API Framework                |
+-------------------------------------------------------------------------+
|                                                                         |
|   +---------------------------+       +-----------------------------+   |
|   |        Intent APIs        |       |      Integration APIs       |   |
|   | - Network Design & Sites  |       | - ITSM (ServiceNow)         |   |
|   | - Policy & Segmentation   |       | - IPAM (Infoblox / BlueCat) |   |
|   | - Provisioning & Onboard  |       | - SIEM (Splunk / QRadar)    |   |
|   | - Network Assurance / AI  |       | - Event Webhooks            |   |
|   +---------------------------+       +-----------------------------+   |
|                 |                                    |                  |
|                 +-----------------+------------------+                  |
|                                   |                                     |
|                                   v                                     |
|                 +-----------------------------------+                   |
|                 |     REST API Gateway (TCP 443)    |                   |
|                 | Token Auth (/dna/system/api/...)  |                   |
|                 | Task Engine (/dna/intent/api/...) |                   |
|                 +-----------------------------------+                   |
|                                   |                                     |
|           +-----------------------+-----------------------+             |
|           v                                               v             |
|   [ Campus Core & Distribution ]                  [ Access & Wireless ] |
|   Catalyst 9500 / 9600 Switches                   Catalyst 9200 / 9300  |
+-------------------------------------------------------------------------+

Catalyst Center REST API Architecture

The Catalyst Center API catalog is structured into functional domains that address distinct operational lifecycles across the enterprise infrastructure:

1. Intent APIs (Northbound Interface)

Intent APIs provide access to core controller capabilities, allowing automation scripts and orchestration systems to express business outcomes rather than low-level device configurations. The Intent API suite is grouped into primary functional areas:

• Authentication and System: Manages authentication tokens, system health, and administrative settings under /dna/system/api/v1/.
• Sites and Network Design: Defines multi-tier physical hierarchies (areas, buildings, and floors) and global network settings (DHCP servers, DNS, NTP, and AAA servers).
• Network Device and Inventory: Discovers, tracks, and extracts hardware specifications, serial numbers, software versions, and interface states across managed infrastructure.
• Configuration and Templates: Deploys CLI templates, day-N configuration changes, and software image management (SWIM) across designated device groups.
• Topology: Generates physical, Layer 2, Layer 3, and virtual overlay topology graphs.
• Assurance and Issues: Surfaces AI-driven telemetry, client connection health, RF analytics, and automated root-cause failure analysis.

2. Integration APIs

Integration APIs provide bidirectional synchronization between Catalyst Center and third-party IT management systems. Common integration targets include Information Technology Service Management (ITSM) platforms like ServiceNow for automated change-management ticketing and CMDB synchronization, and IP Address Management (IPAM) solutions like Infoblox for automated subnet provisioning.

Authentication Workflow and Token Management

All RESTful interactions with Cisco Catalyst Center require TLS encryption (HTTPS on TCP port 443). To prevent transmitting cleartext credentials on every request, Catalyst Center enforces a token-based authentication mechanism.

+-------------------------------------------------------------------------+
|               Catalyst Center Token Authentication Workflow             |
+-------------------------------------------------------------------------+
                                                                           
  [ Automation Client ]                           [ Catalyst Center ]      
           |                                               |               
           | 1. POST /dna/system/api/v1/auth/token         |               
           |    Header: Authorization: Basic <Base64>      |               
           | --------------------------------------------> |               
           |                                               |               
           | 2. HTTP 200 OK                                |               
           |    Body: {"Token": "eyJhbGciOi..."}           |               
           | <-------------------------------------------- |               
           |                                               |               
           | 3. GET /dna/intent/api/v1/network-device      |               
           |    Header: X-Auth-Token: <Token>              |               
           | --------------------------------------------> |               
           |                                               |               
           | 4. HTTP 200 OK + Device Inventory JSON        |               
           | <-------------------------------------------- |               

Step-by-Step Authentication Process

1. Submit Basic Credentials: The client initiates authentication by sending an HTTP POST request to the token authentication endpoint:

   POST /dna/system/api/v1/auth/token HTTP/1.1
   Host: catalyst-center.example.com
   Authorization: Basic YWRtaW46Q2lzY28xMjMh
   Content-Type: application/json
   

   The Authorization header contains the word Basic followed by a single space and the Base64-encoded representation of the username and password in username:password format (e.g., admin:Cisco123! encodes to YWRtaW46Q2lzY28xMjMh).

2. Receive Token Payload: If the credentials are valid, Catalyst Center returns an HTTP 200 OK status code with a JSON response body containing the authentication token:

   {
     "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI..."
   }
   

3. Authorize Subsequent Requests: For all subsequent API operations (inventory queries, site creation, topology requests), the client passes this string in a custom HTTP header named X-Auth-Token:

   GET /dna/intent/api/v1/network-device HTTP/1.1
   Host: catalyst-center.example.com
   X-Auth-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
   Accept: application/json
   

Token Expiration and Refresh Strategies

Catalyst Center authentication tokens have a finite lifetime—typically 1 hour (3,600 seconds) from issuance. After expiration, the controller rejects any request utilizing the expired token with an HTTP 401 Unauthorized status code.

Production network automation scripts handle token expiration using one of two design strategies:

• Proactive Expiration Tracking: The script records the timestamp when the token was acquired. Before executing any API transaction, the script calculates the elapsed time. If elapsed time exceeds 50 minutes (3,000 seconds), the script proactively requests a fresh token before proceeding.
• Reactive Interception (Retry Handler): The script executes requests using the cached token. If an HTTP 401 Unauthorized response is received, an exception handler catches the status code, triggers the authentication workflow to fetch a new token, updates the session headers, and replays the original request.

Cisco Catalyst Center Authentication Lifecycle

Core Intent API Endpoints

Enterprise automation scripts commonly interact with several foundational Intent API endpoints to audit network state, visualize connections, and gather diagnostics:

1. Network Device Inventory (/dna/intent/api/v1/network-device)

The network device endpoint retrieves detailed inventory records for managed hardware. When invoked without parameters via GET /dna/intent/api/v1/network-device, it returns an array of all devices in the domain. The query can be constrained using URL query parameters:

• managementIpAddress=10.10.20.81: Filters for a specific device IP.
• hostname=core-sw01: Filters by device hostname.
• macAddress=00:50:56:a1:b2:c3: Filters by hardware MAC address.
• family=Switches and Hubs: Constrains results to specific product families (e.g., Routers, Wireless Controller).

2. Site Topology (/dna/intent/api/v1/topology/site-topology)

The site topology API retrieves the hierarchical site relationship structure, mapping enterprise sites, campus buildings, and individual floor layouts. Complementary endpoints under /dna/intent/api/v1/topology/ provide Layer 2 link maps (/l2-topology) and Layer 3 routing neighbors (/l3-topology), detailing physical interface connections and neighbor adjacencies across the campus fabric.

3. Command Runner (/dna/intent/api/v1/network-device-poller/cli/read-request)

While intent-based management emphasizes declarative models, engineers frequently require raw diagnostic output from network devices to verify operational conditions. The Command Runner API enables programmatic dispatch of read-only CLI commands across managed devices:

• Strict Read-Only Enforcement: Command Runner permits only non-disruptive, read-only operational EXEC commands (such as show version, show ip route, show ip interface brief, and show cdp neighbors). Any attempt to submit configuration commands (e.g., configure terminal, interface GigabitEthernet0/1, shutdown) is immediately rejected by the controller's safety validation parser.

Core Catalyst Center Intent API Endpoints Reference

Task-Based Asynchronous API Execution Pattern

Because network controllers orchestrate thousands of distributed nodes, long-running operations—such as software image distribution, site template provisioning, or multi-device CLI polling—cannot execute synchronously within a standard HTTP request-response cycle. Holding an HTTP connection open while waiting for dozens of switches to execute a command would result in TCP socket timeouts, thread starvation, and brittle client behavior.

To ensure scalability, Catalyst Center uses a task-based asynchronous processing pattern:

+-------------------------------------------------------------------------+
|                   Task-Based Asynchronous Execution Flow                |
+-------------------------------------------------------------------------+
                                                                           
  [ Automation Client ]                           [ Catalyst Center ]      
           |                                               |               
           | 1. POST .../cli/read-request                  |               
           |    Body: {"commands": ["show ver"], ...}      |               
           | --------------------------------------------> |               
           |                                               |               
           | 2. HTTP 202 Accepted                          |               
           |    Body: {"response": {"taskId": "uuid-123"}}  |               
           | <-------------------------------------------- |               
           |                                               |               
           | 3. GET /dna/intent/api/v1/task/uuid-123       |               
           | --------------------------------------------> |               
           |                                               |               
           | 4. HTTP 200 OK (no fileId in progress yet)     |               
           | <-------------------------------------------- |               
           |    [ Sleep 3-5 seconds ]                      |               
           |                                               |               
           | 5. GET /dna/intent/api/v1/task/uuid-123       |               
           | --------------------------------------------> |               
           |                                               |               
           | 6. HTTP 200 OK                                |               
           |    Body: {"isError": false,                   |               
           |           "progress":                         |               
           |             "{\"fileId\": \"file-999\"}"}      |               
           | <-------------------------------------------- |               
           |                                               |               
           | 7. GET /dna/intent/api/v1/file/file-999       |               
           | --------------------------------------------> |               
           |                                               |               
           | 8. HTTP 200 OK + Raw Command Output JSON      |               
           | <-------------------------------------------- |               

The Asynchronous Polling Lifecycle

1. Initiate Request: The client sends a POST or PUT request targeting an execution-intensive endpoint (such as Command Runner).
2. Receive HTTP 202 Accepted: The controller queues the operation internally and immediately responds with an HTTP 202 Accepted status code. The response body contains an execution tracking object with a taskId (UUID):

   {
     "response": {
       "taskId": "f2a1b3c4-5678-90ab-cdef-1234567890ab",
       "url": "/dna/intent/api/v1/task/f2a1b3c4-5678-90ab-cdef-1234567890ab"
     },
     "version": "1.0"
   }
   

3. Poll Task Status: The client enters a polling loop, executing periodic GET requests against /dna/intent/api/v1/task/{taskId} at configured intervals (e.g., every 3 to 5 seconds).
4. Evaluate Task Completion: The client examines key fields in the task status response:
   • isError: Boolean flag indicating whether the task failed (true or false).
   • failureReason: Text describing the error when isError is true.
   • endTime: Present once the task has finished.
   • progress: A status string. For Command Runner, Cisco's documented pattern is that progress becomes a JSON string such as {"fileId":"<id>"} when the output file is ready.
5. Extract Result File: The client parses the JSON string in progress (for example, json.loads(task["progress"])["fileId"]) and submits a final GET request to /dna/intent/api/v1/file/{fileId} to retrieve the complete command output.

Practical Python Automation Script Walkthrough

The following complete, production-grade Python script illustrates the entire lifecycle: authenticating to Cisco Catalyst Center, querying device inventory to discover a core switch UUID, dispatching a read-only CLI command via Command Runner, polling the asynchronous task, and printing the resulting output.

import time
import json
import requests
from requests.auth import HTTPBasicAuth
import urllib3

# Suppress TLS verification warnings for lab environments with self-signed certs
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

CONTROLLER_IP = "10.10.20.80"
USERNAME = "admin"
PASSWORD = "Cisco123!"
BASE_URL = f"https://{CONTROLLER_IP}"


def get_auth_token(base_url, username, password):
    """Authenticates via HTTP Basic Auth and returns an X-Auth-Token string."""
    token_url = f"{base_url}/dna/system/api/v1/auth/token"
    headers = {"Content-Type": "application/json"}
    
    response = requests.post(
        token_url,
        auth=HTTPBasicAuth(username, password),
        headers=headers,
        verify=False,
        timeout=15
    )
    response.raise_for_status()
    token_data = response.json()
    return token_data["Token"]


def get_first_device(base_url, token):
    """Retrieves the first reachable switch from the network device inventory."""
    inventory_url = f"{base_url}/dna/intent/api/v1/network-device"
    headers = {
        "X-Auth-Token": token,
        "Accept": "application/json"
    }
    params = {"family": "Switches and Hubs"}
    
    response = requests.get(
        inventory_url,
        headers=headers,
        params=params,
        verify=False,
        timeout=15
    )
    response.raise_for_status()
    devices = response.json().get("response", [])
    
    if not devices:
        raise RuntimeError("No switches discovered in Catalyst Center inventory.")
    
    target = devices[0]
    print(f"Targeting Device: {target.get('hostname')} (ID: {target.get('id')})")
    return target["id"]


def run_read_command(base_url, token, device_id, command):
    """Dispatches a read-only CLI command via Command Runner (asynchronous)."""
    runner_url = f"{base_url}/dna/intent/api/v1/network-device-poller/cli/read-request"
    headers = {
        "X-Auth-Token": token,
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {
        "commands": [command],
        "deviceUuids": [device_id]
    }
    
    response = requests.post(
        runner_url,
        headers=headers,
        json=payload,
        verify=False,
        timeout=15
    )
    response.raise_for_status()
    task_info = response.json().get("response", {})
    return task_info.get("taskId")


def poll_task_completion(base_url, token, task_id, max_retries=15, interval=3):
    """Polls the task endpoint until completion, extracting the fileId."""
    task_url = f"{base_url}/dna/intent/api/v1/task/{task_id}"
    headers = {
        "X-Auth-Token": token,
        "Accept": "application/json"
    }
    
    print(f"Polling Task {task_id}...")
    for attempt in range(1, max_retries + 1):
        response = requests.get(task_url, headers=headers, verify=False, timeout=10)
        response.raise_for_status()
        task = response.json().get("response", {})
        
        if task.get("isError"):
            raise RuntimeError(f"Task failed: {task.get('failureReason')}")
        
        progress = task.get("progress", "")
        if "fileId" in progress:
            print(f"Task completed on attempt {attempt}.")
            # Command Runner puts a JSON string such as {"fileId": "..."} in progress
            return json.loads(progress).get("fileId")
        
        time.sleep(interval)
    
    raise TimeoutError(f"Task {task_id} timed out after {max_retries * interval} seconds.")


def download_command_output(base_url, token, file_id):
    """Downloads the raw text file output generated by Command Runner."""
    file_url = f"{base_url}/dna/intent/api/v1/file/{file_id}"
    headers = {
        "X-Auth-Token": token,
        "Accept": "application/json"
    }
    
    response = requests.get(file_url, headers=headers, verify=False, timeout=15)
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    # 1. Acquire Token
    token = get_auth_token(BASE_URL, USERNAME, PASSWORD)
    print("Successfully acquired X-Auth-Token.")
    
    # 2. Discover Target Switch
    device_uuid = get_first_device(BASE_URL, token)
    
    # 3. Submit Read-Only CLI Command
    cmd = "show ip interface brief"
    task_id = run_read_command(BASE_URL, token, device_uuid, cmd)
    
    # 4. Poll Asynchronous Task
    file_id = poll_task_completion(BASE_URL, token, task_id)
    
    # 5. Retrieve File Output
    if file_id:
        output = download_command_output(BASE_URL, token, file_id)
        print("\n--- Command Output ---")
        print(json.dumps(output, indent=2))