How To Generate Authentication Token For FMC REST API Interactions
PDF(189.8 KB) View with Adobe Reader on a variety of devices
ePub(258.1 KB) View in various apps on iPhone, iPad, Android, Sony Reader, or Windows Phone
Mobi (Kindle)(196.0 KB) View on Kindle device or Kindle app on multiple devices
Updated:August 11, 2020
This document describes how an Application programming interface (API) administrator can authenticate to Firepower Management Center (FMC), generate tokens and use them for any further API interactions.
Cisco recommends that you have knowledge of these topics:
Firepower Management Center (FMC) features and configuration. (Config Guide)
Firepower Management Center that supports REST APIs (version 6.1 or higher) with REST API enabled.
REST clients like Postman, Python scripts, CURL, etc.
REST APIs are increasingly popular due to the lightweight programmable approach that network managers can use to configure and manage their networks. FMC supports configuration and management using any REST Client and also using the in-built API explorer.
Enabling REST API on FMC
Step 1. Navigate to System>Configuration>REST API Preferences>Enable REST API.
Step 2. Check the Enable REST API checkbox.
Step 3. Click Save, a Save Successful dialog box is displayed when the REST API is enabled, as shown in the image:
Creating a user on FMC
As a best practice to use the API infrastructure on FMC is to keep UI users and script users separate. Refer the User Accounts for FMC Guide for the understanding of various user roles and the guidelines for creating a new user.
Steps To Request an Authentication token
Step 1. Open your REST API Client.
Step 2. Set the client to make a POST command, URL: https://<management_center_IP_or_name>/api/fmc_platform/v1/auth/generatetoken.
Step 3. Include the username and password as a basic authentication header. The POST body should be blank.
For example, an authentication request using Python:
Example from a GUI based client like Postman, as shown in the image:
Sending subsequent API requests
Note: What you see in the output are the response headers and not the response body. The actual response body is blank. The important header information that needs to be extracted is X-auth-access-token, X-auth-refresh-token, and DOMAIN_UUID.
Once you have authenticated successfully to FMC and extracted the tokens, for further API requests you need to leverage below information:
Add the header X-auth-access-token <authentication token value> as a part of the request.
Add the headers X-auth-access-token <authentication token value> and X-auth-refresh-token <refresh token value> in requests to refresh the token.
Use the Domain_UUID from the authentication token in all REST requests to the server.
With this header information, you can successfully interact with the FMC using REST APIs.
Troubleshoot common issues
The request and response body of the POST sent for the authentication are blank. You need to pass the basic authentication parameters in the request header. All the token information is returned via the response headers.
When using the REST client, you may see errors related to the SSL certificate problem due to a self-signed certificate. You can turn off this validation depending on the client you are using.
User credentials cannot be used for both REST API And GUI interfaces simultaneously, and the user will be logged out without warning if used for both.
The FMC REST API authentication tokens are valid for 30 minutes and can be refreshed up to three times.