Study guide
15.1 Cisco Catalyst Center Intent APIs and Authentication Workflows
Cisco ENCOR 350-401 CCNP Enterprise Core
Track your progress as you read
Finished sections get a check mark.
1 Introduction & Exam Overview
0.1 Cisco 350-401 ENCOR Exam Logistics, Blueprint Structure, and Certification Paths 0.2 Preparation Strategy, Lab Environment Setup, and Practical Test Pacing
2 Enterprise Campus Architecture and High Availability
1.1 Enterprise Network Design: Two-Tier, Three-Tier, Fabric, and Cloud Architectures 1.2 High Availability Architecture: Device Redundancy, FHRPs, and Stateful Switchover (SSO) 1.3 Quality of Service (QoS) Architecture, Classification, Queuing, and Configuration Interpretation
3 Cisco Software-Defined Architecture: SD-WAN and SD-Access
2.1 Cisco Catalyst SD-WAN: Control, Management, and Data Planes 2.2 Cisco SD-Access Architecture: Control Plane, Data Plane, and Fabric Node Roles 2.3 SD-Access Campus Interoperability: Integrating Traditional Networks with Fabric
4 Device and Network Virtualization Technologies
3.1 Device Virtualization: Type 1/2 Hypervisors, Virtual Machines, and Virtual Switching 3.2 Data Path Virtualization: VRF-Lite, GRE Tunneling, and IPsec VPN Fundamentals 3.3 Network Virtualization Overlays: LISP and VXLAN Encapsulation Mechanics
5 Layer 2 Infrastructure: Trunking, EtherChannel, and Spanning Tree
4.1 802.1Q Trunking, Native VLAN, and Dynamic Trunking Protocol Troubleshooting 4.2 EtherChannel Bundling: Static, LACP, and PAgP Implementation and Verification 4.3 Spanning Tree Architecture: RSTP, MST, and STP Protection Mechanisms
6 Layer 3 Routing: OSPF Multi-Area and Protocol Comparison
5.1 Enterprise Routing Principles: Distance Vector vs. Link-State, EIGRP, and OSPF 5.2 OSPFv2 and OSPFv3 Multi-Area Architecture: LSAs, Area Types, and Summarization 5.3 Policy-Based Routing (PBR) Architecture, Configuration, and Route-Maps
7 Exterior Routing: BGP Peering and Path Selection
6.1 External BGP (eBGP) Peering, States, Neighbor Adjacencies, and Timers 6.2 BGP Path Attributes and the Step-by-Step Best Path Selection Algorithm
8 IP Services and First-Hop Redundancy
7.1 Time Synchronization: Network Time Protocol (NTP) and Precision Time Protocol (PTP) 7.2 Network Address Translation: Static NAT, Dynamic NAT, and PAT/Overload 7.3 First Hop Redundancy Protocols: HSRP and VRRP Implementation and Failover
9 IP Multicast Architecture and Protocols
8.1 Multicast Addressing, IGMPv2/v3 Host Membership, and the RPF Check 8.2 Protocol Independent Multicast Sparse Mode (PIM-SM) and Rendezvous Point Discovery 8.3 Anycast RP with MSDP, Source-Specific Multicast (SSM), and Bidirectional PIM
10 Network Diagnostics, Monitoring, and Telemetry
9.1 Network Diagnostic Tools: Conditional Debugging, Traceroute, SNMPv3, and Syslog Logging 9.2 Flexible NetFlow (FNF) Architecture: Flow Records, Exporters, and Monitors 9.3 Switched Port Analyzer: Local SPAN, Remote SPAN (RSPAN), and Encapsulated RSPAN (ERSPAN)
11 Performance Monitoring and Model-Driven Assurance
10.1 IP Service Level Agreements (IP SLA) Probes, Responder, and Route Tracking 10.2 Cisco Catalyst Center: Assurance Dashboards, AI Analytics, and Machine Reasoning Workflows 10.3 Model-Driven Telemetry and Programmable Interfaces: NETCONF and RESTCONF Verification
12 Device Access Control and AAA Architecture
11.1 Device Line Protection: Console, Aux, VTY, Local Authentication, and Privilege Levels 11.2 AAA Architecture: Comparing RADIUS vs. TACACS+ and Method List Configuration
13 Infrastructure Security: ACLs, CoPP, and API Security
12.1 IPv4 and IPv6 Access Control Lists (ACLs): Standard, Extended, and Named Rules 12.2 Control Plane Policing (CoPP): Protecting the Route Processor with MQC 12.3 REST API Security: Token Authentication, TLS Transport, and Rate Limiting
14 Enterprise Network Security Design: ISE, TrustSec, and MACsec
13.1 Endpoint Security Architecture: 802.1X, Cisco ISE Posture, and Profiling 13.2 Next-Generation Firewalls (FTD) and Enterprise Threat Defense Design 13.3 Cisco TrustSec (Security Group Tags) and MACsec (802.1AE) Layer 2 Encryption
15 Network Automation Fundamentals: Python, JSON, and YANG
14.1 Python Fundamentals for Network Engineers: Data Types, Control Flow, and Libraries 14.2 JSON Data Encoding: Syntax, Formatting Rules, and Python Serialization 14.3 YANG Data Modeling: Modules, Tree Structures, and Data Representation
16 Controller REST APIs and RESTCONF Implementation
15.1 Cisco Catalyst Center Intent APIs and Authentication Workflows 15.2 Cisco Catalyst SD-WAN Manager (vManage) REST APIs and Device Interaction 15.3 RESTCONF Protocol Operations: HTTP Verbs, Datastores, and Response Codes
17 Event-Driven Automation and Infrastructure Orchestration
16.1 Cisco Embedded Event Manager (EEM) Applet Architecture and Event Detectors 16.2 Configuration Management: Comparing Ansible, Puppet, Chef, and SaltStack 16.3 Infrastructure as Code (IaC) Principles with Terraform in Enterprise Networks
15.1 Cisco Catalyst Center Intent APIs and Authentication Workflows
Key Takeaways Explain This Topic AI
Cisco Catalyst Center (formerly DNA Center) exposes RESTful Intent APIs that translate high-level enterprise policy into device-level configurations, alongside Integration APIs for external platforms like ServiceNow and Infoblox.
Authentication uses HTTP Basic Authentication submitted via a POST request to /dna/system/api/v1/auth/token, yielding a JSON response with a Token string required in the X-Auth-Token header for all subsequent calls.
Catalyst Center authentication tokens remain valid for 1 hour (3,600 seconds) by default, requiring proactive renewal scheduling or reactive re-authentication handling upon intercepting HTTP 401 Unauthorized errors.
Essential Intent API endpoints include GET /dna/intent/api/v1/network-device for inventory discovery, GET /dna/intent/api/v1/topology/site-topology for Layer 2/3 topology graphs, and POST /dna/intent/api/v1/network-device-poller/cli/read-request for executing non-disruptive, read-only operational commands.
High-latency and configuration tasks follow an asynchronous execution model: the controller responds with HTTP 202 Accepted and a taskId, requiring clients to poll GET /dna/intent/api/v1/task/{taskId} until the task's progress field contains a fileId, then retrieve the output via GET /dna/intent/api/v1/file/{fileId}.
Last updated: October 2026
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
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 ).
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..."
- }
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
Stage HTTP Method & URI Required Request Headers Expected Response Code Response Artifact
Token Generation POST /dna/system/api/v1/auth/token Authorization: Basic <base64> , Content-Type: application/json 200 OK JSON object containing {"Token": "<string>"}
Authenticated Request GET / POST / PUT / DELETE /dna/intent/... X-Auth-Token: <token> , Accept: application/json 200 OK / 201 Created / 202 Accepted Target data payload or asynchronous taskId
Expired Token Encounter Any authenticated endpoint X-Auth-Token: <expired_token> 401 Unauthorized Error JSON with authentication failure details
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
- Endpoint URI HTTP Method Primary Purpose Key Query / Body Parameters
- /dna/system/api/v1/auth/token POST Generate session authentication token Basic Auth header ( Authorization )
/dna/intent/api/v1/network-device GET Retrieve device hardware inventory managementIpAddress , hostname , macAddress , family
- /dna/intent/api/v1/network-device/count GET Return total count of managed network devices None
- /dna/intent/api/v1/topology/site-topology GET Retrieve site hierarchy and building layout None
/dna/intent/api/v1/network-device-poller/cli/read-request POST Execute read-only CLI commands across devices Body: {"commands": ["show ..."], "deviceUuids": ["..."]}
/dna/intent/api/v1/task/{taskId} GET Poll operational progress of an asynchronous task URL path parameter: taskId
/dna/intent/api/v1/file/{fileId} GET Download raw file artifacts (e.g., CLI command output) URL path parameter: fileId
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
Initiate Request: The client sends a POST or PUT request targeting an execution-intensive endpoint (such as Command Runner).
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"
- }
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).
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.
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))