Overview
The REST API authentication works as follows:
- The authentication uses HTTPS as the transport for all the Cisco REST API access.
- Clients perform authentication with this service by invoking a POST on this resource with HTTP Basic Auth as the authentication mechanism. The response of this request includes a token-id. Token-ids are short-lived, opaque objects that represents client’s successful authentication with the token service.
- Clients then access other APIs by including the token id as a custom HTTP header “X-auth-token”. If this token is not present or expired, then API access will return an HTTP status code of “401 Unauthorized”
- Clients can also explicitly invalidate a token by performing a DELETE operation on the token resource.
- The username/password for the HTTPS session should be configured with privilege 15.
Resource Summary for Client Authentication
| |
|
|
|
|
|
|
|
|
|
token-id |
/api/v1/auth/token-services /api/v1/auth/token-services/{opaque-token-id} |
Y Y |
Y N |
N N |
N Y |
Token Service Resource
The token service resource represents the authentication service that allows clients to perform authentication and obtain a token-id.
History
|
|
|
IOS XE 3.10 |
Introduced for the CSR1000V platform |
IOS XE 3.14 |
Introduced for ASR1001-X and ASR1002-X platforms |
JSON Representation
"kind": "collection#auth-token",
"items: [ { auth-token JSON object }+ ]
Authenticate and Create a New Token
The initial HTTP request is performed by clients to authenticate and obtain a token so that it can invoke other APIs. The HTTP POST response contains an ‘opaque’ URL to be used for HTTP GET and DELETE requests.
Resource URI
|
|
|
POST |
/api/v1/auth/token-services |
Example
JSON Request
POST /api/v1/auth/token-services
JSON Response
Content-Type: application/json
"kind": "object#auth-token",
"link":http://host/api/auth/token-services/johnDoe,
"expiry-time": "00:15:00"
In subsequent API accesses, the token-id must appear as a custom HTTP header for successful invocation of APIs.
For example:
Resource URI
|
|
|
GET |
/api/v1/auth/token-services |
Example
JSON Request
GET /api/v1/auth/token-services
JSON Response
Token Resource
A token represents successful authentication of a client.
History
|
|
|
IOS XE 3.10 |
Introduced for the CSR1000V platform |
IOS XE 3.14 |
Introduced for ASR1001-X and ASR1002-X platforms |
Properties
|
|
|
Required for POST and PUT
|
|
kind |
string |
Not applicable |
Must be “object#auth-token” |
token-id |
string |
Not applicable |
Authentication token that must be included as a custom HTTP header X-auth-token value in all API requests |
link |
string |
Not applicable |
Token resource URL. |
expiry-time |
string |
Not applicable |
Idle period in hh:mm:ss format. |
JSON Representation of a Token
"kind": "object#auth-token",
"expiry-time": "{string}"
Resource URI
|
|
|
GET |
/api/v1/auth/token-services/{opaque-token-id} |
Example
JSON Request
GET /api/v1/auth/token-services/johnDoe
JSON Response
Content-Type: application/json
"kind": "object#session-token",
"expiry-time": "00:15:00"
Invalidate a Token
Typically tokens automatically expire after 15 minutes. However, clients can perform explicit invalidation of a token by doing a DELETE on the token resource.
Resource URI
|
|
|
DELETE |
/api/v1/auth/token-services/{opaque-token-id} |
Feedback