Platform Introduction

Note: To access all documentation be sure you are registered and Sign In. Non-signed in users can only access publicly available documentation.

The Cisco APIs Console gives you direct access to Cisco’s APIs, which in turn, gives you access to the data and resources they provide. Our APIs help you manage, configure, and scale your applications that use Cisco data. Whether you need information to support the sale of Cisco’s hardware and software products, to support your Cisco Service needs, or for your mobile applications; the Cisco API Console will scale to meet your needs. ## Our Platform The Cisco API Console is an easy-to-use resource for our partners, customers, and internal developers who need to access APIs to get Cisco data and services. The API Console provides an intuitive, secure experience to help you learn about and integrate our API's. Whether you are building Web applications, mobile apps, or smart devices, the Console will help you integrate your internal tools, systems, and applications in a simple, secure, scalable manner. The API Console guides you through the steps necessary to register applications; use sample code, obtain tokens, and select the proper grant types for your application(s). The Console supports secure data and credentials, using industry standard authentication and role-based authorization. ## Getting Started Once you are logged in, you can access to all the APIs available to you and get detailed information about each API. ## Introduction

This section will explain the steps needed to be taken to on-board to Web APIs provided by Cisco. This section will cover obtaining a user account, assigning party and role assignments to that user account for a specific company, and using Cisco's API Console for the registration of a client application that will call Cisco's Web APIs.

These instructions are intended for Cisco's Customers or Partners that intend to create client applications from Cisco Provided APIs.

## Prerequisites

There are four prerequisites needed before a user can initiate the API service calls and obtain access to the product information available from the tenants. The first two steps consist of user and application registration; while the last two steps are related to development and metrics use. The steps necessary are:

Perform Onboard Registration: This is for user registration. This process, also referred to as on-boarding, is where the following actions take place:
- User registers for a CCO ID--or they may use their existing one if they have already registered with Cisco--and is then nominated by a Cisco Administrator to become a Delegated Administrator (DA).
- The DA will associate other CCO ID users to a company and assign them roles, which gives them access to the API console. Only one DA is assigned by Cisco, however, that DA may assign other users to the role of DA.
Registration of a client application creates a “unique client identifier” that will identify your client application to the Cisco Token services.
- 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.
- Registration also subscribes the client application to one (1) or more of the APIs provided by Cisco.
Develop Application
- This is the client code developed by the customer or partner.
Utilize Cisco's Token services to acquire an OAuth v2.0 access-token(s).

Once these steps have been completed successfully, the user can then place API calls to their chosen APIs. Once calls have been made to the APIs, the user can review various usage and performance metrics that are associated with the API service calls.

DOWNLOAD
	API Console User Guide (5.0 MB)
	Token Developer Guide (359 KB)

Register Application

This section describes the information needed, and the steps that need to be performed to register an API application. Use the following steps to register an application.

Step 1: From the “Home” page, click on “My Apps & Keys” link and then click Register a New App, The “Register an Application” page will open:

Required Fields

Name

Optional Fields

Application Description

Step 2: In the "Name of your application" field, fill in the name of the application that is being registered.

Step 3: Select the OAuth2.0 Grant Type (see Token Developer Guide for expanded explanations of the OAuth2.0 Grant Types) to be used with the application. The available choices are:

Authorization Code
Client Credentials
Implicit
Resource Owner Credentials
Refresh Token (Token Validation)–Only valid for Authorization Code or Resource Owner Credential grant types.

At least one or more OAuth v2.0 Grant type requested from this Client must be selected (checked). If either the Authorization Code or Implicit grant types are chosen, then entering a Redirection URL (where your client is known to execute) is required. The URL must be chosen at the time of registration. If the URL is not chosen, it cannot be added/edited at a later date.

The current recommendation for grant type usage:

Client Credentials Grant are for a hosted client applications (Machine to Machine) from a trusted environment.
AuthCode Grant for Web Server application (from a trusted environment).
Implicit Grant for JavaScript or Native Mobile/Desktop applications.
Resource Owner Grant is not recommended.

One client application rarely utilizes more than one of the above grant types.

Step 4: Select an API to be used with the application.
Step 5: Read the Terms of Service, then check the Terms of Service agreement check box.
Step 6: Click the Register Application button.

After the application registration is completed the console window displays an "Application Registered" message.

This is simply the confirmation page detailing the application has been successfully registered, and that the Client ID and the Client Secret have been issued. The user will be able to refer to their “My Applications” page at any time to retrieve their Client ID and Client Secret.

Along with the registration confirmation, the window displays the following information:

The API(s) registered with the application.
Application: The name of the registered application.
Client ID / Client Secret: The Client ID and Client Secret are used together as input for the Cisco Token services (as they identity the client application) to acquire an access-token or grant/code. Only access-tokens accompany an API call.

The Client ID and Client Secret are the OAuth 2.0 credentials used by the API service call to obtain the access token. It is recommended that users return to the “My Applications” page to retrieve these credentials. It is also recommended to keep the Client ID/Client Secret private and not to share that information (for example, using the same restrictions as sharing a password).

Status: Indicates the status of the application.
Registered: Indicates the length of time since the application was registered.

Step 7: Click on “My Applications” either below the header graphic, or the link directly below the “Client ID” pane. This will open the user’s account page.

## Getting the Access Token

When the application is registered in the APIconsole, and one or more of the grant types were chosen to use with that specific client application, it is only permitted to make token requests with the grant types chosen. If there was no grant type chosen at registration, then it will not be possible to request authorization via that specific grant-type flow.

At least one or more OAuth v2.0 Grant type requested from this Client must be selected (checked). If either the Authorization Code or Implicit grant types are chosen, then entering a Redirection URL (where your client is known to execute) is required. The URL must be chosen at the time of registration. If the URL is not chosen, it cannot be added/edited at a later date.

The current recommendation is to use:

Client Credentials Grant are for a hosted client applications (Machine to Machine) from a trusted environment
AuthCode Grant for Web Server application (from a trusted environment) - Implicit Grant for JavaScript or Native Mobile/Desktop applications
Resource Owner Grant is not recommended.

One client application rarely utilizes more than one of the above grant types.

If the grant type choice was either Authorization Code or Implicit – it is necessary to enter a specific URI for the executing location of the client application (the location of the redirection).

If the grant type choice was either Authorization Code or Resource Owner Password grants –the option of also receiving a refresh token in the response will be available. The refresh token can be use to gain a newer access-token in a fast-track fashion.

API Console Register an Application: https://apiconsole.cisco.com/apps/register

Cisco has externalized two specific OAuth services/APIs (token and authorization) to facilitate client application integration. Those OAuth APIs are REST style APIs, JSON formatted responses, and have customer/partner reachable endpoints.

If an OAuth v2.0 library for a specific programming language is being used, or IDE is being programmed for the client application development, it will be necessary to refer to that specific OAuth v2.0 library specification on how to input into the respective objects the required calls and parameters. Several programming language specific OAuth v2.0 libraries can be found at: http://oauth.net/2/ .

The section below describes the token and authorization endpoints, flow of requests/responses, and the required/optional inputs for all four of the primary OAuth v2.0 grant types.

The Resource Owner's may manage their grants against the Cisco Authorization servers at these locations (SSO login will be required): https://cloudsso.cisco.com/as/oauth_access_grants.ping

## Using Tokens to Make Calls

These instructions are intended for Cisco's Customers or Partners that intend to create client applications from Cisco Provided APIs.

Using your access-token on an API request call

Some information on using your access-token on an API request:

Cisco's default lifetime for an access-token is 3600 seconds (1 hour), after which time you will need to reacquire 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 anytime 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 and in some grant types even a refresh_token.

{  
        "token_type": "Bearer",  
        "expires_in": 3599,  
        "refresh_token": "VdjcZSbkceN2ll9Cd9JGq1lsKqw5x4Sj7dwWLNscsP", 
        "access_token": "TJQIE4IWRfL6RcA2PhCxKcFE1SDT"  
}

Now you are ready to place your destination API call, utilizing your token_type and access_token from the grant response, the recommended method for using the access-token is to insert that information on our API request as a HTTP header Authorization statement like:

Authorization: <token_type> <access-token>
Authorization: Bearer KSBs9TtSLTTM6vBptZJLNaoPtTqP

This process would be the same for SOAP or REST API requests, and those API endpoints will start with a URI like: https://api.cisco.com/...

For the API you desire to call, please see the specific API Developer Guide Reference for the details of the Endpoint, and input parameter for the request of that specific API.

Below is an example of calling the destination API ("Hello API") in REST utilizing the access-token on the API request.

The same process is also used for a destination SOAP service (not available in Hello API to date).

If you need to search for a particular API, simply click the search button in the upper-right corner of the screen. Further information can be found in the API User Guide and the FAQs .

version 7 as of 1 year ago by Rafi

Previous: Overview
Up: Overview
Next: Oauth 2.0 Topics

Platform Introduction

Docs Navigation