Skip to content
Catalyst SD-WAN Lab Guide

Authentication

Catalyst SD-WAN Manager supports a variety of authentication mechanisms.

  • From 20.18
  • Create an API key under profile
  • Obtain the XSRF token using the API gateway URL and API key
  • Use the API key along with the XSRF token in headers: X-XSRF-TOKEN: <xsrf-token>, Authorization: Bearer <apikey>

Using API Key

Section titled “Using API Key”

API key authentication was introduced in Cisco Catalyst SD-WAN Manager 20.18 as an alternative to traditional session-based authentication with JSESSIONID cookies.

This is the authentication method used throughout this lab. Before you run the API requests in later sections, you first use your API key to obtain an XSRF token. After that, each request sends both values in the HTTP headers:

  • Authorization: Bearer {apikey} identifies and authorizes the API client.
  • X-XSRF-TOKEN: {X_XSRF_TOKEN} satisfies Manager’s cross-site request forgery protection for state-changing operations such as POST, PUT, and DELETE.

The rest of this section explains the authentication flow. The hands-on Bruno requests are covered later in Practice with Bruno.

Authentication API Key

To obtain the API key:

  • In Cisco SD-WAN Manager, click your username at the top of the page, then choose My profile
  • In the API token area, click Generate
  • SD-WAN Manager generates and displays the API key
  • Copy or download the API key and store it securely

You can also find the organization name in Manager:

  • Open Administration > Settings > Organization name
  • Copy the value from the Organization name field

The direct Manager API key flow shown below only needs the Manager hostname and API key. The organization name is useful for Cisco-hosted cloud and API gateway workflows.

org

Using the API key and Manager hostname, make a GET request to the token endpoint:

GET https://{vmanage}:{port}/dataservice/client/token
Headers:
  content-type: application/json
  Authorization: Bearer {apikey}

The response body is the XSRF token as a plain string, with no JSON wrapper. Save it as X_XSRF_TOKEN.

token

All subsequent lab requests use this same header pattern:

Headers:
  content-type: application/json
  Authorization: Bearer {apikey}
  X-XSRF-TOKEN: {X_XSRF_TOKEN}

Session Based

Section titled “Session Based”

Cisco Catalyst SD-WAN Manager still supports a traditional REST API access control that is based on sessions (JSESSIONIDs). With this authentication method, Cisco Catalyst SD-WAN Manager creates a session for each user after successful login.

Session based authentication

Log in with a username and password to establish a Session

POST /j_security_check with content type x-www-form-urlencoded in the request header.

Submit the username and password as j_username and j_password in the body.

GET https://{vmanage}:{port}/dataservice/j_security_check
Body:
  j_username: {username}
  j_password: {password}

Authentication

When a user authenticates successfully, the response body is empty, but the response header includes a valid session cookie.

The session token is in the response HTTP cookie: JSESSIONID=<session hash>.

Get XSRF prevention token

Get an XSRF prevention token, necessary for most POST operations:

GET https://{vmanage}:{port}/dataservice/client/token
Headers:
  content-type: application/json
  Cookie: JSESSIONID={jsessionid}

Example with Bruno:

Get XSRF Token

The response body is the CSRF token (plain string, no JSON wrapper). Save it as X_XSRF_TOKEN.

All subsequent requests must include:

Headers:
  content-type: application/json
  X-XSRF-TOKEN: {X_XSRF_TOKEN}
  Cookie: JSESSIONID={jsessionid}
  • X-XSRF-TOKEN — proves the request is intentional (CSRF protection), required for POST/PUT/DELETE operations
  • Cookie: JSESSIONID — identifies your authenticated session, required for all requests

Example using Bruno:

API Request

Practice with Bruno

Section titled “Practice with Bruno”

Open Bruno and load the collection located in the bruno/sdwan-sandbox folder of this repository. The authentication requests for this page are in bruno/sdwan-sandbox/Authentication.

Before running any request, select the sandbox environment from the environment picker (top-right dropdown). This environment contains the shared variables used by the collection, including {{vmanage}}, {{port}}, and {{X-XSRF-TOKEN}}. Set the secret variables {{vmanage}} and {{apikey}} before you start.

The Authentication folder demonstrates the API key authentication flow:

Step1: Get the CSRF token

  • Go to the Authentication folder
  • Use the 01 - Get Auth Token request and hit send
  • This sends GET /dataservice/client/token with the Authorization: Bearer {{apikey}} header
  • The response body is the CSRF token as a plain string
  • The post-response script automatically saves it to the Bruno variable {{X-XSRF-TOKEN}}

Step2: Validate Manager access

  • Use the 02 - Get Status request and hit send
  • This sends GET /dataservice/client/about
  • The request includes both Authorization: Bearer {{apikey}} and X-XSRF-TOKEN: {{X-XSRF-TOKEN}}
  • A successful response confirms that the API key and CSRF token are working

Step3: Run an authenticated API request

  • Use the 03 - Fabric Devices request and hit send
  • This sends GET /dataservice/device
  • The request reuses the same authentication headers from the environment
  • The response lists the devices known to SD-WAN Manager