Cisco ACI Learning Guide

APIC REST authentication hinges on one detail: the access token is short-lived, and every subsequent request depends on how you acquire and pass it. This section documents APIC login and token handling (including the “Token Trail Method” workflow) so you can build repeatable request flows.

OverviewThis section covers APIC login via REST, token extraction, and how to attach the token to follow-on API calls. Use it when you need deterministic automation for ACI configuration, inventory, or operational queries against APIC.

Quick ReferencePurpose

Endpoint (APIC base URL)

Method

Notes

Login (obtain token)

/api/aaaLogin.json

POST

Returns imdata containing a token

Logout (invalidate token)

/api/aaaLogout.json

POST

Use current token

Attach token to API calls

Any /api/*

GET/POST/PUT/DELETE

Header: APIC-cookie = token

Token Trail Method (workflow)

Acquire → Reuse → Refresh (on 401)

-

Track token issuance time + expiry window

Example headerAPIC-cookie: <token>

Visio-style request flow (text diagram)[Client] --POST /api/aaaLogin.json--> [APIC]

<--200 + imdata[].aaaLogin.attributes.token--

+--GET /api/node/class/fvTenant.json

Header: APIC-cookie: <token>

+--If 401/expired token--> repeat POST /api/aaaLogin.jsonParametersParameter

Type

Required

Description

apic_url

string

Yes

APIC base URL, e.g. https://apic.example.com

username

string

Yes

APIC local user (or LDAP-backed user)

password

string

Yes

Password for the APIC user

verify_tls

boolean

Default: true

Whether to verify APIC TLS certificate

timeout_seconds

integer

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 Exampleimport 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 FormatLogin 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 Practices401 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._

...