Mental model
Cisco objective 3.9.a names Catalyst SD-WAN. Catalyst SD-WAN (previously SD-WAN by Cisco / Viptela) uses vManage as its controller. API base: https://vmanage.example.com/dataservice/....
Auth is more involved than Catalyst Center or Meraki — two steps, session cookie + CSRF token.
Step 1 — login
curl -k -c cookies.jar \
-X POST -d 'j_username=admin&j_password=password' \
https://vmanage.example.com/j_security_check
- URL ends in
/j_security_check(JAAS-style auth endpoint, not JSON). - Body is URL-encoded form, NOT JSON.
- Response: empty if success. HTTP 200.
Set-Cookie: JSESSIONID=...saved incookies.jar.
Failure returns a HTML page with <title>login</title> instead of an error code — check the body on first attempt.
Step 2 — CSRF token
curl -k -b cookies.jar \
https://vmanage.example.com/dataservice/client/token
Response body is the raw token string (not JSON). Save it as $CSRF.
From here on, every write (POST/PUT/DELETE) requires -H "X-XSRF-TOKEN: $CSRF". Reads work with just the cookie.
3.9.a — List devices
curl -k -b cookies.jar https://vmanage.example.com/dataservice/device
Response (abbreviated):
{
"data": [
{
"deviceId": "10.1.1.1",
"system-ip": "1.1.1.1",
"host-name": "vmanage-01",
"device-type": "vmanage",
"device-model": "vmanage",
"reachability": "reachable",
"status": "normal"
},
{
"deviceId": "10.2.2.1",
"system-ip": "2.2.2.1",
"host-name": "edge-site-01",
"device-type": "vedge",
"device-model": "vedge-cloud",
"reachability": "reachable",
"status": "normal"
}
],
"header": {"columns": [...]}
}
device-type tells you what kind: vmanage / vsmart / vbond (controllers), vedge / cedge (data-plane edges).
Other common endpoints
| Endpoint | Returns |
|---|---|
GET /dataservice/device | All devices (controllers + edges) |
GET /dataservice/device/counters | Per-device counters (reachable, warning, invalid) |
GET /dataservice/device/interface?deviceId=10.2.2.1 | Interfaces on a specific device |
GET /dataservice/statistics/approute | Application-aware route stats |
GET /dataservice/template/device | Device templates (configuration) |
Python with requests
import requests
requests.packages.urllib3.disable_warnings()
BASE = "https://vmanage.example.com"
s = requests.Session()
# login
s.post(f"{BASE}/j_security_check",
data={"j_username": "admin", "j_password": "password"},
verify=False)
# CSRF token
csrf = s.get(f"{BASE}/dataservice/client/token", verify=False).text
s.headers["X-XSRF-TOKEN"] = csrf
# list devices
r = s.get(f"{BASE}/dataservice/device", verify=False)
for d in r.json()["data"]:
print(f"{d['host-name']:25} {d['system-ip']:12} {d['device-type']:10} {d['reachability']}")
Session + cookie + header-on-session covers both auth steps cleanly.
Common gotchas
- Login returns an HTML login page on failure. HTTP 200 but with
<html>in the body. Check content-type / body shape, not the status. - CSRF token mismatch on write operations if you re-login without re-fetching the token.
- URL space is
dataservice, notapiorrest— unlike Catalyst Center and Meraki. - Multi-tenant deployments need extra
tenantNamequery param on some endpoints. - Older vManage versions have slightly different auth endpoints — docs vary by version.
FAQ
Why is auth so complex vs Catalyst Center? vManage inherited the auth pattern from the Viptela product. Cisco acquired Viptela in 2017; the API retains its original shape. Modern Cisco controllers (Catalyst Center, Nexus Dashboard) use token-only.
Is there an SDK? cisco-sdwan (community) and various vendor sample scripts. For 200-901, requests is enough.
What is Catalyst SD-WAN Manager? Rebranded name for vManage. Same product, same API.
Where is the DevNet Sandbox? developer.cisco.com has an always-on Catalyst SD-WAN sandbox with a small demo fabric.