Introduction

What is REST?

REpresentational State Transfer, commonly abbreviated as REST, is a software architectural style that defines a set of constraints to be used for creating web services. This allows for rapid communication between networking applications and devices, with consistent inputs and outputs and predictable results.

📘

What is an API?

An Application Programming Interface (API) is a set of routines, protocols, and tools to define interactions between software applications.

The HPE Aruba Networking AOS-CX REST API is known as such because it is an API that conforms to REST standards.

To learn more about REST API, check out the HPE Aruba Networking YouTube video below.

Enabling the AOS-CX API

In order for the AOS-CX device to receive and process API calls, a few requisite commands must first be executed on the switch to enable API access.

1. There must be a user on the switch who belongs to the "administrators group" and has a password set. This user would then be allowed to access the REST API. In the below example, replace the username "admin" and password "mypassword" with your own username and password respectively.

8320(config)# user admin group administrators password plaintext mypassword

2. The switch must have the access mode for the HTTPS server set to either "read-only" or "read-write." By default, the switch's HTTP server is set to "read-only" mode, which allows only GET requests, with the exception of a few POST/PUT methods (see here for specifics). To utilize the API calls for DELETE, PUT, and POST, execute the below command with "read-write" mode specified.

8320(config)# https-server rest access-mode read-write

3. The HTTPS server must be enabled on the VRF through which the client making the API requests can reach the switch.

8320(config)# https-server vrf default
8320(config)# https-server vrf mgmt

📘

As of v10.04 by default, REST access-mode is set to read-write on the default VRF.

Logging in with the API

📘

cURL

Going forward, the REST call examples will use cURL, which is an open-source command-line interface tool.
More information on cURL can be found in the cURL subsection of the Additional Resources page.

To log in to an AOS-CX device through the API, make a REST call using cURL, Postman, the Python requests library, or any other tool that supports the execution of a POST request. The AOS-CX REST API utilizes a cookie to keep session state information, in firmware version 10.09+ a CSRF token is required in addition to the cookie. This session cookie and token are encrypted and contain session-specific data. When sending the POST request to login, the header x-use-csrf-token: true must be provided. After a successful login, the received CSRF token must be provided as a header x-csrf-token:<token_value as well as the cookie returned must be provided as well.

An example using cURL is shown here:

curl -H "accept: */*" -H "x-use-csrf-token: true" -d "" -i -k -X POST 'https://10.22.5.169/rest/latest/login?username=admin&password=mypassword'
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 22 Aug 2025 22:33:53 GMT
Content-Length: 0
Connection: keep-alive
Set-Cookie: id=juvTFbVmnRQ19hN9aEY8jw==; Path=/; HttpOnly; Secure; SameSite=Lax
X-Csrf-Token: ukf2-1rmDs7B8kXNevc1uQ==
X-Oscx-User-Info: eyJ1c2VyIjoiYWRtaW4iLCJsZXZlbCI6MTUsInR5cGUiOiJMT0NBTCIsIm1ldGhvZCI6IkxPQ0FMIn0=
Cache-Control: no-cache, no-store
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains;
Content-Security-Policy: script-src 'self' 'sha256-Vr7caLfhPjPEeQNH5n7dEGm7EYCQWxH16Tc4u9c+mM8=' 'sha256-pZnUCLouq90XQpzO5bFR4C0G0pJRvY5xPmrg/dmgEHM=' 'sha256-O4CRj7+Nmv2ySF/Vs4cIcPFqpN5Igd5Ykpqk3eliQqU=' 'sha256-vXYk13Wej/l4lSpIdMJf01ZeeKWzQgUnbcn6zZYCByg='; font-src 'self' https://fonts.gstatic.com; style-src 'self' https://fonts.googleapis.com https://cdn.jsdelivr.net; img-src 'self' data:;  connect-src 'self' https://ase.arubanetworks.com https://www.arubanetworks.com; object-src 'none'; media-src 'none'; form-action 'self'; frame-src 'self'; frame-ancestors 'self'; default-src 'self'

curl -H  "accept: application/json" -H "x-csrf-token:ukf2-1rmDs7B8kXNevc1uQ==" --cookie "id=juvTFbVmnRQ19hN9aEY8jw==" -i -k -X GET 'https://10.232.5.169/rest/latest/system/vlans'
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 22 Aug 2025 22:38:49 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 187
Connection: keep-alive
Etag: 3236939ca04edaee876405205f18e181
Cache-Control: no-cache, no-store
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains;
Content-Security-Policy: script-src 'self' 'sha256-Vr7caLfhPjPEeQNH5n7dEGm7EYCQWxH16Tc4u9c+mM8=' 'sha256-pZnUCLouq90XQpzO5bFR4C0G0pJRvY5xPmrg/dmgEHM=' 'sha256-O4CRj7+Nmv2ySF/Vs4cIcPFqpN5Igd5Ykpqk3eliQqU=' 'sha256-vXYk13Wej/l4lSpIdMJf01ZeeKWzQgUnbcn6zZYCByg='; font-src 'self' https://fonts.gstatic.com; style-src 'self' https://fonts.googleapis.com https://cdn.jsdelivr.net; img-src 'self' data:;  connect-src 'self' https://ase.arubanetworks.com https://www.arubanetworks.com; object-src 'none'; media-src 'none'; form-action 'self'; frame-src 'self'; frame-ancestors 'self'; default-src 'self'

{"1":"/rest/latest/system/vlans/1","101":"/rest/latest/system/vlans/101","102":"/rest/latest/system/vlans/102","200":"/rest/latest/system/vlans/200","300":"/rest/latest/system/vlans/300"}

Logging out with the API

To log out of an AOS-CX device through the API, a similar POST call must be made, except to a different URI. An example using cURL is below:

curl -X POST "https://192.168.1.1/rest/v10.04/logout"

API Sessions

As of firmware version 10.05, the maximum number of concurrent HTTPS sessions per user per switch is six. There is an upper limit of 48 total sessions per switch. It is best practice to log out of an HTTPS session when you are finished using it.

HTTPS sessions will automatically time out after 20 minutes of inactivity.
HTTPS sessions also have a hard time limit of eight hours, regardless of whether the session is active.

To close all current HTTPS sessions, run the following command in the enable (#) context:

8320# https-server session close all