Skip to content
Log in Sign up My account

5.3 REST API Security

Blueprint 5.3: Describe REST API security

  • Transport security (HTTPS and TLS)
  • Authentication methods: HTTP Basic, API keys, tokens, OAuth 2.0, certificates
  • Authorization and the meaning of 401, 403 and 429
  • How Catalyst Center, SD-WAN Manager and IOS XE RESTCONF secure their APIs
  • Good practice for scripts that call network APIs

Automation moves network changes from people typing at a CLI to programs calling APIs. An API that can push configuration to every switch in the company is a high-value target, so it needs the same protection you give the CLI: encrypt the session, prove who is calling, limit what they can do, and log it. This is a describe objective. You will not configure an API gateway on the exam, but you must recognise the mechanisms and pick the secure option.

The layers of API security

graph LR
  C["Script or app"] -- "1 TLS: is the channel private and is this the real server?" --> S["API endpoint"]
  S --> A{"2 Authentication:<br/>who is calling?"}
  A -- "missing or bad" --> E401["401 Unauthorized"]
  A -- "ok" --> Z{"3 Authorization:<br/>may this caller do this?"}
  Z -- "no" --> E403["403 Forbidden"]
  Z -- "yes" --> R{"4 Rate limit<br/>and input checks"}
  R -- "too many" --> E429["429 Too Many Requests"]
  R -- "bad input" --> E400["400 Bad Request"]
  R -- "ok" --> OK["2xx and an audit log entry"]
Layer Question Mechanisms
Transport Can anyone read or alter the traffic? Is the server genuine? HTTPS (TLS 1.2 or 1.3), certificate validation
Authentication Who is calling? Basic authentication, API keys, tokens (bearer, JWT), OAuth 2.0, client certificates (mutual TLS)
Authorization What may they do? Role-based access control (RBAC), scopes, least privilege
Abuse protection Is the caller behaving? Rate limiting, input validation, timeouts
Accountability What happened? Audit logs that record the identity, the call and the result

Transport: HTTPS and certificates

A REST API is HTTP. Without TLS, every request header (including credentials and tokens) and every body (including configuration and secrets) crosses the network in clear text.

  • Always use HTTPS. Disable the plain HTTP server on network devices that expose APIs.
  • Validate the server certificate. Network devices often ship with self-signed certificates. Tools such as curl -k or Python requests with verify=False skip validation, which is convenient in a lab and dangerous in production, because a man-in-the-middle can present any certificate. In production, install a certificate signed by your enterprise CA on the device and point the client at the CA bundle.
  • Mutual TLS (mTLS) goes one step further: the client also presents a certificate, so the server authenticates the client at the TLS layer.

Exam trap

HTTP Basic authentication only Base64-encodes username:password. Base64 is an encoding, not encryption, and anyone can decode it. Basic authentication is acceptable only inside HTTPS, and preferably only to obtain a token.

Authentication methods

Method How it works Strengths Weaknesses
HTTP Basic Authorization: Basic base64(user:pass) on every request Simple, universally supported Sends the real password every time. Needs TLS
API key A long random string in a header, assigned to an app Easy to issue and revoke per app Often long-lived, easily leaked in code or logs, identifies an app rather than a person
Session token or cookie Log in once, receive a token or cookie, send it on later calls Password sent only once, token expires Must be protected like a password while valid
Bearer token (often a JWT) Authorization: Bearer <token>; whoever holds it is trusted Stateless, short lifetime, can carry scopes Theft equals impersonation until expiry
OAuth 2.0 An authorization server issues access tokens to a client, optionally on behalf of a user who consents Delegated, scoped, the app never sees the user's password More moving parts
Client certificate (mTLS) TLS handshake proves the client holds a private key Strong, nothing secret is sent Certificate lifecycle to manage

Tokens and JWTs

A JSON Web Token (JWT) has three Base64url parts separated by dots: header.payload.signature. The payload carries claims such as the subject, issuer, expiry (exp) and roles. The signature lets the server check that the token was issued by a trusted party and not changed.

Exam trap

A signed JWT is not encrypted. Anyone who holds it can decode the payload and read the claims. Never put secrets inside a JWT, and treat the whole token as a credential: anyone who has it can use it until it expires.

OAuth 2.0 in one picture

sequenceDiagram
  participant App as Client app
  participant AS as Authorization server
  participant API as Resource server API
  App->>AS: Request token (client credentials, or user consent via authorization code)
  AS->>App: Access token, scope=read:devices, expires_in=3600
  App->>API: GET /devices with Authorization Bearer token
  API->>API: Check signature, expiry and scope
  API->>App: 200 OK with data
  App->>API: POST /devices (needs write scope)
  API->>App: 403 Forbidden

The key ideas are delegation (the app receives a token, not the user's password) and scope (the token says exactly what it may do). Refresh tokens let an app get new access tokens without asking the user again.

Authorization and status codes

Authentication proves identity. Authorization decides whether that identity may perform this particular operation. Network platforms implement it with roles: for example, an observer role that can only read, and an administrator role that can change configuration.

Code Meaning Typical cause
200 OK Success GET returned data
201 Created Resource created POST or PUT created an object
202 Accepted Work started asynchronously Catalyst Center returns a task ID to poll
204 No Content Success with no body RESTCONF PATCH or DELETE
400 Bad Request Malformed request Invalid JSON, wrong field
401 Unauthorized Not authenticated Missing, wrong or expired credentials or token
403 Forbidden Authenticated but not allowed Role lacks permission
404 Not Found Wrong URL or object Typo in the path
429 Too Many Requests Rate limit hit Script looping too fast
500 Internal Server Error Server failed Server-side fault

Exam trap

401 means "I do not know who you are" (despite its name, it is about authentication). 403 means "I know who you are, and you may not do this". A script with an expired Catalyst Center token gets 401 and must request a new token. A read-only user trying to push a template gets 403, and a new token will not help.

How Cisco platforms secure their APIs

Catalyst Center (formerly DNA Center)

  1. The client sends POST /dna/system/api/v1/auth/token with HTTP Basic authentication over HTTPS.
  2. Catalyst Center returns a JSON body with a Token value.
  3. Every later request carries the token in the X-Auth-Token header.
  4. The token expires (60 minutes by default). After that the API returns 401 and the client requests a new token.
  5. What the user can do is controlled by Catalyst Center roles (RBAC), so the API respects the same permissions as the GUI.
POST https://catc.example.com/dna/system/api/v1/auth/token
Authorization: Basic <base64 of user:password>

HTTP/1.1 200 OK
{"Token": "eyJhbGciOi..."}

GET https://catc.example.com/dna/intent/api/v1/network-device
X-Auth-Token: eyJhbGciOi...

Catalyst SD-WAN Manager (formerly vManage)

The classic flow is session based:

  1. POST /j_security_check with form fields j_username and j_password. A successful login returns a JSESSIONID session cookie.
  2. GET /dataservice/client/token with that cookie returns a cross-site request forgery (XSRF) token.
  3. Requests that change state (POST, PUT, DELETE) must carry both the cookie and the X-XSRF-TOKEN header.

Recent releases also offer token-based login. Check the API documentation for your release on developer.cisco.com.

IOS XE RESTCONF

RESTCONF on a router or switch uses HTTPS and HTTP Basic authentication against the local database or AAA. The user needs privilege level 15.

username automation privilege 15 algorithm-type scrypt secret Aut0-Mat3!
!
ip http secure-server
no ip http server
ip http authentication local
restconf
!
! Optional: only the automation subnet may reach the HTTPS server
ip access-list standard AUTOMATION-HOSTS
 permit 192.168.100.0 0.0.0.255
ip http access-class ipv4 AUTOMATION-HOSTS

The exact ip http access-class syntax depends on the release; older releases take a numbered ACL (ip http access-class 10). To use TACACS+ or RADIUS instead of local users, use ip http authentication aaa together with the AAA method lists from the AAA page.

Platform How the client authenticates Token or session carried in
Catalyst Center Basic auth to the token endpoint X-Auth-Token header
SD-WAN Manager (classic) Form login to j_security_check JSESSIONID cookie plus X-XSRF-TOKEN header for changes
IOS XE RESTCONF HTTP Basic on every request Authorization: Basic header (over HTTPS)
Meraki Dashboard API key per user Authorization: Bearer header (older: X-Cisco-Meraki-API-Key)

Exam trap

Do not mix up the header names. X-Auth-Token belongs to Catalyst Center. JSESSIONID and X-XSRF-TOKEN belong to SD-WAN Manager. RESTCONF on IOS XE uses plain Basic authentication on each request.

Good practice for API clients

Do Do not
Read credentials from environment variables or a secrets vault Hard-code usernames, passwords or keys in scripts or commit them to Git
Use a dedicated service account per automation tool, with the least privilege it needs Share one administrator account between all scripts and people
Use short-lived tokens and handle 401 by re-authenticating Cache a token forever or loop on 401
Validate server certificates against your CA Disable certificate checks in production
Back off and retry on 429, honouring any Retry-After header Hammer the API in a tight loop
Send credentials in headers or the body over HTTPS Put credentials or tokens in the URL query string (it ends up in logs and browser history)
Validate input on the server side and log every call with the caller identity Trust whatever the client sends

The OWASP API Security Top 10 is a widely used list of the most common API weaknesses, such as broken object-level authorization and broken authentication. It is worth reading once even though the exam does not test it by name.

Lab: secure RESTCONF on R1

Topology: R1 (Catalyst 8000v) Gi1 192.168.100.1/24, Host1 (Ubuntu) at 192.168.100.10 with curl and Python 3. See Lab Setup.

  1. On R1, configure the RESTCONF block from this page, including no ip http server and ip http access-class.

  2. From Host1, request the interface list with valid credentials:

    curl -k -u automation:'Aut0-Mat3!' \
  -H "Accept: application/yang-data+json" \
  https://192.168.100.1/restconf/data/ietf-interfaces:interfaces

    Expected: HTTP 200 and a JSON body listing the interfaces. -k skips certificate validation because R1 uses a self-signed certificate. Note it as a lab-only shortcut.

  3. Repeat with a wrong password and add -w '%{http_code}\n' -o /dev/null to print only the status code. Expected: 401.

  4. Try plain HTTP: curl http://192.168.100.1/restconf/data/ietf-interfaces:interfaces. Expected: connection refused, because the HTTP server is off.
  5. Capture the HTTPS request on Host1 with sudo tcpdump -i any -A port 443. The payload is unreadable. Then, purely as a demonstration, enable ip http server and compare a Basic-auth request over port 80: the Authorization: Basic header is visible and decodes with echo <value> | base64 -d. Disable the HTTP server again.
  6. Remove 192.168.100.0/24 from AUTOMATION-HOSTS (or test from a host outside it). Expected: the HTTPS connection is refused.
  7. Write a five-line Python script that reads the username and password from environment variables (os.environ["RC_USER"]) rather than from the code, and prints the status code.

Expected verification on R1:

R1# show ip http server status | include server status|secure server status|access class
HTTP server status: Disabled
HTTP secure server status: Enabled
...
R1# show platform software yang-management process
confd            : Running
nesd             : Running
syncfd           : Running
...

Process names in the YANG management output vary by release. The key line is that the HTTP server is disabled and the secure server is enabled.

Quick check

A script receives 403 when it calls an API that worked yesterday. Will requesting a new token fix it?

Probably not. 403 means the caller is authenticated but not authorized. The role assigned to the account, or the scope of the token, does not allow this operation. An expired token produces 401.

Why is HTTP Basic authentication acceptable for RESTCONF on IOS XE but not over plain HTTP?

Basic authentication only encodes the credentials in Base64. Over HTTPS the TLS session encrypts the header; over HTTP anyone capturing the traffic can decode the username and password.

Which two headers does SD-WAN Manager need on a POST in the classic session-based flow?

The JSESSIONID cookie from the login, and the X-XSRF-TOKEN header carrying the token from /dataservice/client/token.

References