Authentication

The BCS OI API is REST-based and authentication is done via a JSON Web TokenJWT, which you must add in the Authentication header for every request. To generate such a token, the application sends a request to the token endpoint. Registering an application with the CX Cloud API Gateway Portal generates all the details needed to successfully complete the authentication sequence.

JSON Web Token Generation

To obtain this JWT, the application must first make a request to the CX Cloud API GW token endpoint at https://api-cx.cisco.com/torii-auth/v1/token, providing the Client ID and Client Secret in the body.

For example:

POST /torii-auth/v1/token/ HTTP/1.1
Host: api-cx.cisco.com
Content-Type: application/json
Content-Length: 178

{
    "grantType": "client_credentials",
    "clientId": "{{Client ID}}",
    "secret": "{{Client Secret}}",
    "scope": "api.bcs.manage"
}

The body of the response contains the JWT ("accessToken"):

{
    "tokenType": "Bearer",
    "expiresIn": 3200,
    "accessToken": "{{JWT}}",
    "scope": [
        "api.bcs.manage"
    ]
}

The JWT has an expiration of 3200 seconds after which a new token has to be requested by repeating the process above.

NOTE: To obtain a Client ID/Client Secret pair, see Application registration.

Base URI

Every API request will begin with the following Base URI where the region has to be populated with the value as provided during the Application registration.

https://api-cx.cisco.com/{{region}}/bcs/v2/

Consuming the BCS Operational Insights API

When the JWT is generated, you can add the JWT in the Authentication header and consume the API.

GET /us/bcs/v2/inventory/assets HTTP/1.1
Authorization: Bearer {{JWT}}
Accept: application/json
Host: api-cx.cisco.com