BCI Services APIs – Onboarding Process

This chapter provides information on the following:

  • API Registration
  • Registering Cisco BCI Services APIs
  • Access-token Generation
  • BCI Services API URLs

API Registration

Registering an API provides you with a client ID and secret that will be required to generate an access token.

  • Use http://cs.co/apiplatform to register for one or more APIs. Registration creates the client credentials along with name assignment, description, and subscribes the client application to one (1) or more of the OAuth v2.0 grant types requested for their client application.

  • To have a single Client ID and secret users must register for all APIs using the same application.

Understanding Developer Portal

The Developer portal has two tabs

Registering Cisco Services APIs

To register Cisco Services APIs, perform the following:

  • Log in to Cisco APIs Developer site.

  • Search for a resource API. For example, “Inventory”.

alt text

  • Click the API name that needs to be registered.

  • Click the Request API access button on the top right corner of the screen.

alt text

  • Click the New Application button.

alt text

  • Enter the information and select the type of grant (Client Credentials Grant is the preferred grant type) and click Add.

alt text

  • Accept the terms and conditions and click Request API access. If API access request is granted, Client Id and Client secret information is displayed.

alt text

  • If the API access request is granted, Client Id and Client secret information is displayed. Click OK to register the API.

alt text

Note: Click Application details to view the Application home page. The application home page shows the registered APIs and usage metrics.

  • Store the Client ID and Client secret, for future authentication and to access the APIs.

Working with My applications

  • Click My applications to view the list of applications.

alt text

  • Click the desired application to view the API registration details of the application.

alt text

Access-token Generation

Use your ClientID and Client secret to generate your Access-token using https://cloudsso.cisco.com/as/token.oauth2?grant_type=client_credentials&client_id={{CLIENTID}}&client_secret={{CLIENTSECRET}} .

Replace {{ClientID}} and {{ClientSecret}} with the IDs obtained during API registration.

For example, you will get the below response after invoking the above URL.

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

Each API header must contain “Authorization” and “Bearer {{token}}” as key value pair.

Based on the above format, the header should have “Authorization” and “Bearer Er2cdpFDGNsQPSsyyhBO7izCvqG5” as key value pair.

Access token is required to invoke each API and must be part of the header.

Note:

Cisco's default lifetime for an access-token is 3600 seconds (1 hour), after which time you will need to acquire a new access-token either through the use of a refresh token (if available), or by replicating the authorization process over again.

You may re-authorize (redo the OAuth v2.0 grant flow) at any time to get a new access-token (with a fresh expiry).

Regardless of which OAuth v2.0 grant type flow you used to obtain your access-token, ultimately you will end up with the following variable-value pairs: token_type, expires_in, access_token.

BCI Services API URLs

The following table lists the Services API URLs.

API Name Category URLs
chassis-ldos inventory https://apx.cisco.com/cs/api/v1/inventory/chassis-ldos
config-register-warnings inventory https://apx.cisco.com/cs/api/v1/inventory/config-register-warnings
crash-network-elements inventory https://apx.cisco.com/cs/api/v1/inventory/crash-network-elements
network-element-count inventory https://apx.cisco.com/cs/api/v1/inventory/network-element-count
network-element-reachability inventory https://apx.cisco.com/cs/api/v1/inventory/network-element-reachability
network-element-summary-by-product-family inventory https://apx.cisco.com/cs/api/v1/inventory/network-element-summary-by-product-family
new-network-elements inventory https://apx.cisco.com/cs/api/v1/inventory/new-network-elements
reloaded-network-elements inventory https://apx.cisco.com/cs/api/v1/inventory/reloaded-network-elements
snmp-pass-network-elements inventory https://apx.cisco.com/cs/api/v1/inventory/snmp-pass-network-elements
sw-changed-network-elements inventory https://apx.cisco.com/cs/api/v1/inventory/sw-changed-network-elements
hardware-summary-by-product-family inventory https://apx.cisco.com/cs/api/v1/inventory/hardware-summary-by-product-family
hardware-summary-by-product-id inventory https://apx.cisco.com/cs/api/v1/inventory/hardware-summary-by-product-id
network-element-summary-by-product-family inventory https://apx.cisco.com/cs/api/v1/inventory/network-element-summary-by-product-family
software-conformance-trend conformance https://apx.cisco.com/cs/api/v1/conformance/software-conformance-trend
software-flexible-conformance-trend conformance https://apx.cisco.com/cs/api/v1/conformance/software-flexible-conformance-trend
configuration-best-practices-by-technology conformance https://apx.cisco.com/cs/api/v1/conformance/configuration-best-practices-by-technology
software-conformance-by-track conformance https://apx.cisco.com/cs/api/v1/conformance/software-conformance-by-track
software-conformance conformance https://apx.cisco.com/cs/api/v1/product-alerts/software-conformance
custom-config-summary-by-template product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/custom-config-summary-by-template
field-notice-summary product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/field-notice-summary
hardware-eol-milestones-by-product-family product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/hardware-eol-milestones-by-product-family
hardware-eol-summary-by-month product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/hardware-eol-summary-by-month
security-advisory-summary product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/security-advisory-summary
software-eol-summary-by-milestone product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/software-eol-summary-by-milestone
config-bp-by-network-element-trend product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/config-bp-by-network-element-trend
config-bp-by-risk-trend product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/config-bp-by-risk-trend
config-bp-by-technology-trend product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/config-bp-by-technology-trend
config-bp-rule-trend product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/config-bp-rule-trend
custom-config-trend product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/custom-config-trend
field-notice-trend product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/field-notice-trend
security-advisory-trend product-alerts https://apx.cisco.com/cs/api/v1/product-alerts/security-advisory-trend