Like most modern network devices, the ASA supports the REST API. However, it’s a bit different in some ways. For one, the ASA requires that you use HTTPS, rather than HTTP. Not an unreasonable request for a security appliance.

Also, the ASA needs to run a REST agent. Unlike many other devices, this is a separate installable component. Physical ASA’s need an extra file downloaded from Cisco and installed. Virtual ASA’s already have the file downloaded, but you still need to install it.

At the time of writing, version 1.32 of the REST API is current. Have the documentation available as you read through this article.

You’ll need to download and install the REST client. Before that, check the compatibility matrix to make sure you use a supported version for your ASA.

If you are using multi-mode, check out the Caveats section later in this article.

The basic procedure is:

1. Copy the image file to your ASA
2. Verify and install the image
3. Enable REST
4. Make a REST call

Copy the SPA file to disk0 on the ASA. Then, verify and install the image with the rest-api image disk0:/filename.spa command. This does not cause a reboot.

You must also enable the REST API before using it. The first part of this is to enable the http server with http server enable. If you’re using the ASDM, this is already enabled. Also, remember to specify allowed IP’s and interfaces for management.

HTTP authentication also needs configuration. This can be anything that AAA supports, like LOCAL or RADIUS. The account privileges vary depending on what you need to do. Basic monitoring needs level 3, and GET requests need level 5. Any configuration changes need level 15.

Finally, the agent can be enabled with the rest-api agent command.

To test this, open a browser, and go to https://x.x.x.x/api/objects/networkobjects. This should return some basic JSON data. As long as it doesn’t return an error, you’re good to go.

There are two ways you can authenticate. Basic, which uses a simple username and password in every request, and Token-based.

Basic Authentication uses special headers containing the username and the Base64-encoded password. You have to pass these headers with every request. This is usually a simple method to use when testing in Postman.

There are two ways you can try this. The simplest option is to get Postman to do the work:

1. Go to the Authorization tab
2. Set the type to Basic Auth
3. Enter the username and password
4. Postman will generate the headers automatically (which you can see with the preview request button)

If you’re not using Postman, you have to work out the headers yourself:

1. Create a string, made up of your username and password, separated by a colon
   • For example, admin:c1sc0
2. Use some tool to encode it into Base64
   • This will look something like  QWRtaW46UGFzc3dvcmQ=
3. Create a header called Authorization. The value starts with “Basic ” and is followed by the Base64 string
   • For example, Basic QWRtaW46UGFzc3dvcmQ=​​

If you’re going to test this in Postman, be wary of self-signed certificates. Often ASA’s use self-signed certificates, which Postman does not tollerate by default. To fix this:

1. Go to File -> Settings
2. Click the General tab
3. Disable SSL Certificate Verification

Token authentication uses a special request to create a session. The token is then passed with each request, rather than a username and password. This is the best option if you’re using code, not Postman.

To create a token:

1. Set the Content-Type header to application/json
2. Set the headers as in Basic Authentication
3. POST the request to https://x.x.x.x/api/tokenservices
4. The ASA will return a result
   • Code 204 (No Content)
   • An X-Auth-Token header, with the token included
5. Save the token to use later

To use a token:

1. Prepare a request as normal
2. Set the X-Auth-Token header, with the token as the value
3. Send the request

To delete the token (that is, to log out):

1. Set the Content-Type header to application/json
2. Set the X-Auth-Token header to the token value
3. DELETE to https://x.x.x.x/api/tokenservices/TOKEN
   • Where TOKEN is the token value

The ASA includes some built-in interactive documentation. To access it, browse to https://x.x.x.x/doc. Sometimes the ASA seems to strip the https out of the URL and the page won’t load. If this happens, just add it back in and try again.

On the left is a list of categories. As an example, click Save. In the middle of the screen are all the resources. Save includes a single resource, called /api/commands/writemem. Click on the resource for more detail. You can also see the headers that need to be set for this request.

Each resource lists the methods that it supports. Writemem supports only the POST method. If you click the method, you have the option of sending it to the ASA (see the screen on the right). This really does send the query to the ASA, so be cautious when you use it.

Also on the right-hand side of the screen are tabs to see the request and response information. The Request Info tab shows what you posted to the ASA. The Response Texttab shows the JSON data that the ASA returned.

All responses include a status code. Errors codes will be 400, 404, 405, 5xx.

Error responses may also include JSON data with more information, as shown below.

Now it’s time for a few examples. We’re going to write the running-config to disk, send CLI commands, and backup the config. Have a look through the documentation while you try these examples.

1. Set the Content-Type header to application/json
2. Leave the request-body empty
3. Include your authentication header
4. POST the request to /api/commands/writemem
5. If all is good, the ASA returns a 200 code

1. Set the Content-Type header to application/json
2. Set the request-body as shown in the example below. This gets the serial number of the ASA
3. Include your authentication header
4. POST the request to /api/cli
5. If all is good, the ASA returns:
   • A 200 code
   • The result of the command in the message body

1. Set the Content-Type header to application/json
2. Set the request-body as shown in the example below
   • location is the path for the backup
   • passphrase is the password used to encrypt sensitive data
   • Optionally, context specifies the context to back up
3. Include your authentication header
4. POST the request to /api/backup
5. If all is good, the ASA returns a 201 (Created) code

Note, you can restore the backup to an ASA by POSTing to /api/restore. This is disruptive though, as it will reboot the ASA.

There are a few final things you need to know…

Making changes with REST does not prevent making changes with other methods, such as CLI or ASDM. So, keep in mind that other admins could still be making conflicting changes.

REST changes only affect the running-config. Just like in the CLI or ASDM, you still need to save your config.

If you use the aaa authorization command, you need to create a user called enable_1 with a privilege level of 15. RADIUS uses this to parse the config initially, and whenever there are any changes.

Multi-mode has limited support. You can save config, backup/restore config, use token services, and send CLI commands. Fortunately sending CLI commands enables you to do just about everything.