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
API portals – Lists all the APIs developed by Cisco. To register Cisco APIs, refer to Registering Cisco Services APIs.
My application – Lists the application that the user has created. For more information on My application, refer to Working with My applications.
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”.
Click the API name that needs to be registered.
Click the Request API access button on the top right corner of the screen.
- Click the New Application button.
- Enter the information and select the type of grant (Client Credentials Grant is the preferred grant type) and click Add.
- Accept the terms and conditions and click Request API access. If API access request is granted, Client Id and Client secret information is displayed.
- If the API access request is granted, Client Id and Client secret information is displayed. Click OK to register the API.
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.
- Click the desired application to view the API registration details of the application.
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 |