Catalyst Center API: Token Auth, GET Devices, GET Clients

Mental model

Cisco objective 3.9.a says “Obtain a list of network devices by using Meraki, Cisco Catalyst Center, ACI, Cisco Catalyst SD-WAN, or NSO”. 3.9.c adds Catalyst Center clients. This topic is the Catalyst Center half. (See meraki-dashboard-api-first-script for the Meraki half.)

Catalyst Center (formerly DNA Center) is Cisco’s on-prem enterprise controller for Catalyst switches, routers and APs. The REST API lives under https://<dnac>/dna/.

Two-step auth

Catalyst Center requires a short-lived token.

Step 1: trade username/password for a token

curl -k -u admin:password -X POST \
     https://dnac.example.com/dna/system/api/v1/auth/token

• -k skips TLS verification (dev / lab clusters often use self-signed certs).
• -u sends Basic auth with your Catalyst Center username and password.
• -X POST because this is a POST even though no body.
• Response: {"Token": "eyJhbGci..."}.

Save the token. It is valid for ~1 hour.

Step 2: use the token for everything else

curl -k -H "X-Auth-Token: $TOKEN" \
     https://dnac.example.com/dna/intent/api/v1/network-device

Header name is X-Auth-Token (capital X), not Authorization: Bearer.

3.9.a — GET devices

GET /dna/intent/api/v1/network-device

Response (abbreviated):

{
  "response": [
    {
      "hostname": "sw-core-1",
      "managementIpAddress": "10.0.0.1",
      "platformId": "C9300-48U",
      "softwareVersion": "17.12.3",
      "reachabilityStatus": "Reachable",
      "role": "ACCESS",
      "serialNumber": "FCW2345A1BC",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789"
    },
    ...
  ],
  "version": "1.0"
}

Fields you usually use:

• hostname, managementIpAddress, platformId, softwareVersion.
• reachabilityStatus (“Reachable” / “Unreachable” / “Unknown”).
• id (the Catalyst Center-assigned UUID). Needed to drill into details.

Filter queries

GET /dna/intent/api/v1/network-device?family=Switches%20and%20Hubs
GET /dna/intent/api/v1/network-device?role=ACCESS
GET /dna/intent/api/v1/network-device?softwareVersion=17.12.3

Each query param narrows the result. Combine with &.

3.9.c — GET clients

GET /dna/intent/api/v1/client-detail?macAddress=aa:bb:cc:dd:ee:01&timestamp=1696348800000

• macAddress identifies the client.
• timestamp is the point-in-time to look up (Unix epoch milliseconds). Catalyst Center keeps historical state.

Response includes hostname, user, vlan, ap it connected through, SSID, signal, health score.

Lists of clients on a device

GET /dna/intent/api/v1/network-device/<id>/clients

Returns clients the specified device has seen.

Python with requests

import requests, os

BASE = "https://dnac.example.com"
USER, PASS = os.environ["DNAC_USER"], os.environ["DNAC_PASS"]

# 1. token
r = requests.post(f"{BASE}/dna/system/api/v1/auth/token",
                  auth=(USER, PASS), verify=False)
r.raise_for_status()
token = r.json()["Token"]

# 2. devices
headers = {"X-Auth-Token": token}
r = requests.get(f"{BASE}/dna/intent/api/v1/network-device",
                 headers=headers, verify=False)
r.raise_for_status()
for d in r.json()["response"]:
    print(f"{d['hostname']:30} {d['managementIpAddress']:16} {d['reachabilityStatus']}")

With the dnacentersdk library

The SDK handles auth + pagination + retries for you.

from dnacentersdk import DNACenterAPI

api = DNACenterAPI(
    base_url="https://dnac.example.com",
    username="admin", password="password",
    verify=False,
)

for d in api.devices.get_device_list():
    print(d.hostname, d.managementIpAddress)

get_device_list() returns a generator that paginates automatically.

Common gotchas

• TLS cert. Lab clusters are self-signed. -k on curl, verify=False in requests, verify=False in the SDK.
• Token expiry. 1 hour. Re-auth on 401.
• Rate limiting. Catalyst Center documents per-token limits. The SDK handles retries; roll your own in requests.
• Long-running tasks. Many write operations return a taskId (202 Accepted). Poll GET /dna/intent/api/v1/task/<id> until endTime is non-zero.
• Response envelope. Device-related endpoints return {"response": [...]} (wrapped). The SDK unwraps for you.

FAQ

Is this the same API as DNA Center? Yes. Cisco rebranded DNA Center → Catalyst Center in 2024. The hostnames and URL paths still use dnac / dna.

What is the DevNet Sandbox URL for Catalyst Center? developer.cisco.com has an always-on sandbox. Credentials rotate but are on the sandbox page.

Does Catalyst Center expose NETCONF / RESTCONF on managed devices? Catalyst Center is itself a REST API. Underneath, it talks to switches via NETCONF / CLI. You usually do not need to touch the per-device NETCONF when using Catalyst Center as the controller.

What is the “intent” in /dna/intent/api/v1? Catalyst Center is built on the “intent-based networking” idea — you say what you want (intent), it figures out the per-device config. “intent” is literally in the URL.