Use Cisco APIs in Cisco SD-WAN Cloud

API keys for Cisco SD-WAN Cloud

API key, or JSON web tokens (JWT), are unique codes that:

  • grant client access to an application programming interface (API),

  • serve as a password preventing unauthorized access, and

  • are required for Cisco SD-WAN Cloud customer access to Cisco APIs.

A Cisco API key is to be used for Cisco API calls by a specified fabric user. It remains valid until the user is deleted or the user role is changed.

This chapter describes how to acquire a Cisco API key and use Cisco APIs on a Cisco SD-WAN Cloud fabric in Cisco SD-WAN Cloud Release 20.15 and higher.

Obtain a Cisco API key

Cisco SD-WAN Cloud Release 20.15 provides a mechanism to generate an API key directly. Follow these steps to generate an API key and find the gateway URL and Cross-site request forgery protection (CSRF) token values:

Procedure

Step 1

Log into the fabric.

Step 2

Select My Profile from the drop-down menu under your user ID.

Step 3

On the Profile page, select Generate under API token. The API key is generated and displayed.

Step 4

Copy or download the key contents.

Example:

Example generated API key:

{
  "token": "eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ2bGluZ2FtcEBjaXNjby5jb20iLCJpc3MiOiJiOGVkYW
...
a_fcNoeAlVYvrXzDXA",
  "sub": "example@example.com",
  "iss": "b8edab9d-aaaa-4019-9999-f980cd5df3af",
  "aud": "vmanage",
  "userGroup": "[tenantadmin]",
  "tenant": "kdk-va2 - 999999-va-7aaaaaa5 - 640565",
  "duration": 315360000,
  "exp": 2058818495,
  "csrf": "AB0E71CAE...",
  "isAPIKey": true
}

Step 5

Use the endpoint information provided here to find your API gateway URL. In the payload "org" field, enter the "tenant" value from your API key, and in the "apikey" field, enter the "token" value.

Example:

Post 
https://ssp.sdwan.cisco.com/ssp/api/v6/apigw/info/
Payload
{ 
"org": "kdk-va2 - 999999-va-7aaaaaa5 - 640565", 
"apikey": "eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ2bGluZ2FtcEBjaXNjby5jb20iLCJpc3MiOiJiOGVkYW
...
a_fcNoeAlVYvrXzDXA", 
"is_redirect": false 
}
Response
{ 
"gateway_url": "apigw1clouduswest2-1024.viptela.info", 
"org": "kdk-va2 - 999999-va-7aaaaaa5 - 640565" 
}

Note

 

If a new API gateway is provisioned near your geographical location, repeat this process to connect to the new gateway serving your overlay.

Step 6

Using the API key and gateway URL hostname values you received, make a GET request to the endpoint “/dataservice/client/token” to obtain the CSRF token, which is found in the response you will receive.

Example:

Based on the gateway URL returned in this example, the full pathname would be https://apigw1clouduswest2-1024.viptela.info/dataservice/client/token.

Restrictions for using a Cisco API key

Use the Cisco API key to access all Cisco APIs from Cisco SD-WAN Cloud through your SSO login, subject to certain restrictions. Refer to Cisco DevNet for more information on Cisco APIs.

  • Authentication method

    You must specify the Bearer token authentication method in a header field. Use the value you received from your GET request.

  • Cross-site request forgery protection (CSRF/XSRF)

    Your API request header must include an X-XSRF-Token header field to protect against cross-site request forgery. Use the value you received from your GET request.

  • API body use

    You can include an API body as needed, based on the API call you are making.

  • Rate limit

    Real time APIs and bulk APIs are not available. All other APIs can be used, subject to a rate limit of 10 per second. Cisco SD-WAN Manager imposes an API rate limit of 5 per second.

  • No continuous monitoring

    Do not use this feature for continuous monitoring. Refer to the Cisco Catalyst SD-WAN Getting Started Guide for more information on API rate limits.

  • Supported categories

    API calls are provided for only these categories of operations:

    • Certificate management

    • Configuration

    • Device and device inventory

    • Monitoring

    • Troubleshooting tools

  • No NAT configuration

    NAT configuration using REST APIs is not supported.

Cisco API request examples

The examples in this section demonstrate how to use the API key, gateway URL, and CSRF/XSRF token to execute API calls.

GET API request example using Curl

This GET request retrieves the page at the URL specified in the location parameter.

curl --location apigw1clouduswest2-1024.viptela.info/dataservice/settings/configuration/banner'
--header 'X-XSRF-Token: AB0E71CAE...'
--header 'Authorization: Bearer eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ2bGluZ2FtcEBjaXNjby5jb20iLCJpc3MiOiJiOGVkYW
...
a_fcNoeAlVYvrXzDXA'

PUT/POST API request example using Curl

This PUT request sends the data in the data parameter to the page URL specified in the location parameter.

curl --location --request PUT apigw1clouduswest2-1024.viptela.info/dataservice/settings/configuration/banner'
--header 'X-XSRF-Token: AB0E71CAE72C6D...'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ2bGluZ2FtcEBjaXNjby5jb20iLCJpc3MiOiJiOGVkYW
...
a_fcNoeAlVYvrXzDXA'
--data '{"mode":"on","bannerDetail":"check"}'