Cisco ACI Learning Guide

Default: 30

HTTP client timeout for login and API calls

login_path

string

Default: /api/aaaLogin.json

Login endpoint path

logout_path

string

Default: /api/aaaLogout.json

Logout endpoint path

api_path

string

Yes

Follow-on endpoint, e.g. /api/node/class/fvTenant.json

token_header_name

string

Default: APIC-cookie

Header name used for token-based authentication

token_refresh_on_401

boolean

Default: true

Refresh token when APIC returns HTTP 401

Code Example

import time import requests

Darius, 31, network automation engineer

Token Trail Method: Acquire token -> Reuse token -> Refresh on 401

APIC_URL = "https://apic.example.com" USERNAME = "darius" PASSWORD = "REDACTED"

token_header_name = "APIC-cookie" token = None token_acquired_at = 0 token_ttl_seconds_est = 3600

adjust based on your APIC policy/observations

def apic_login(session: requests.Session) -> str: url = f"{APIC_URL}/api/aaaLogin.json" payload = {"aaaUser": {"attributes": {"name": USERNAME, "pwd": PASSWORD}}}

r = session.post(url, json=payload, timeout=30, verify=True) r.raise_for_status()

Expected structure: {"imdata":[{"aaaLogin":{"attributes":{"token":"...","refreshTimeout":"..."}}}]} imdata = r.json().get("imdata", []) attrs = imdata[0]["aaaLogin"]["attributes"] return attrs["token"]

def apic_get(session: requests.Session, api_path: str): global token, token_acquired_at

Reuse token if within an estimated TTL window if token is None or (time.time() - token_acquired_at) > token_ttl_seconds_est: token = apic_login(session) token_acquired_at = time.time()

url = f"{APIC_URL}{api_path}" headers = {token_header_name: token}

r = session.get(url, headers=headers, timeout=30, verify=True)

Refresh on token expiration/invalid token if r.status_code == 401: token = apic_login(session) token_acquired_at = time.time() headers = {token_header_name: token} r = session.get(url, headers=headers, timeout=30, verify=True)

r.raise_for_status() return r.json()

with requests.Session() as session: tenants = apic_get(session, "/api/node/class/fvTenant.json") print(tenants) Response Format

Login response (JSON)

{ "imdata": [ { "aaaLogin": { "attributes": { "token": "TOKEN_VALUE", "refreshTimeout": "3600" } } } ] } Follow-on query response pattern

{ "imdata": [ { "fvTenant": { "attributes": { "name": "TENANT_NAME", "status": "created" } } } ] } Field notes:

• imdata: APIC’s standard list wrapper for managed object results.

• aaaLogin.attributes.token: the string used in APIC-cookie.

• refreshTimeout (from login): server-provided guidance for token lifetime.

Notes & Best Practices

• 401 handling: treat HTTP 401 as “token invalid/expired” and re-run /api/aaaLogin.json before retrying the failed request.

• TLS verification: keep verify=True in production; if you disable verification, pin it to a controlled environment.

• Token reuse window: use `refreshTimeout

_seconds_est based on observed behavior; do not assume a fixed TTL across APIC versions or policies._

• Error payloads: non-2xx responses may include an error object inside an imdata wrapper; log raw response text for triage.

• Visio-style request flow: capture the sequence in your runbooks so token logic stays consistent across scripts.

Visio-style request flow (token trail)

+------------------+ POST /api/aaaLogin.json +-------------------+ | Client (script) | ---------------------------------------> | APIC (auth service)| +------------------+ +-------------------+ | | | 200 + JSON imdata[0].aaaLogin.attributes.token | |<--------------------------------------------------------+ v +------------------+ GET /api/...{resource}.json +-------------------+ | Token stored | ---------------------------------------> | APIC (data service)| | in header | APIC-cookie: <token> +-------------------+ +------------------+ | | | | 200 JSON imdata[...] | |<---------------------------------------------------------------+ v +------------------+ | Token refresh | | on HTTP 401 | +------------------+ | | retry: | POST /api/aaaLogin.json -> new token -> repeat original GET v (loop back to GET) Common endpoints used in token handling

Purpose

Method

Path

Obtain token

POST

/api/aaaLogin.json

Query resources

GET

/api/<apiRoot>/<managedObject>.json (example: /api/node/class/fvTenant.json )

Verify token behavior

GET

same endpoint as your primary workflow

Link to related sections:

• APIC REST query patterns and filters (managed object paths under /api/ )

• Consuming ACI configuration objects (tenant/VRF/EPG classes) using the imdata response wrapper

End of chapter one. 4 more chapters in the full book.