Authentication

The Support APIs are REST-based, sending HTTP GET and POST requests to the Support APIs cloud, authenticating each request by providing a HTTP Authentication header and Bearer access token.

For example:

GET /product/v1/information/serial_numbers/ HTTP/1.1
Authorization: Bearer S0w9Dqsjaredacted08uasdf890NW21S8
Accept: application/json
Host: apix.cisco.com

To obtain this API access token, the application must first make a request to the Cisco Common Identity SSO endpoint at https://id.cisco.com/oauth2/default/v1/token, providing a Client ID/Client Secret associated with the application instance. This set of credentials uniquely identifies the application and its access/roles/permissions with regard to accessing customer support data.

Note: to obtain a Client ID/Client Secret pair, see Application registration

Access-token generation

The access token authentication request is based on the OAuth2 client credentials grant flow, which is a single request/response transaction not requiring any user interaction to complete.

The following details define the authentication HTTP request:

  • HTTP method: POST
  • URL endpoint: https://id.cisco.com/oauth2/default/v1/token
  • Content-Type: application/x-www-form-urlencoded
  • Body: URL-encoded parameters:
    • grant_type: client_credentials
    • client_id: (your application Client ID)
    • client_secret: (your application Client Secret)

The raw request will look something like:

POST /oauth2/default/v1/token HTTP/1.1
Host: id.cisco.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=b441B255redacted09fc5b&client_secret=b441Bredactedaf5b75d886b429

The response includes an access_token field, as well as an expires_in field representing the number of seconds this access token will be good for (e.g. one hour:)

{ 
    "access_token": "Er2cdpFDGNsQPSsyyhBO7izCvqG5",
    "token_type": "Bearer",
    "expires_in": 3599
}

Once the access token has been generated, it must be provided when invoking each API request, as as part of the Authentication header.

Note: the default lifetime for a client credential access-token is 3600 seconds (1 hour) as of this writng. After the expiration time (or at any time prior), the application can acquire a new access-token by repeating the authorization process above.