cisco device activations rc provisioning api · all the services are currently exposed through the...

CISCO DEVICE ACTIVATIONS

RC PROVISIONING API

11/17/2017 RC PROVISIONING API SPEC

1

Contents 1 Introduction ........................................................................................................................................... 3

2 Service Authentication........................................................................................................................... 3

2.1 First Time Access .............................................................................................................. 3 2.1.1 API Manager Portal .................................................................................................................. 3

2.2 Creating client Applications .............................................................................................. 4 3 API Requirements ................................................................................................................................ 10

3.1 Assign Mac Address ........................................................................................................ 10 3.1.1 Request URI ............................................................................................................................ 10

3.1.2 Query Parameters .................................................................................................................. 11

3.1.3 Request Header ..................................................................................................................... 11

3.1.4 Response Attributes ............................................................................................................... 11

3.1.5 Response Body ....................................................................................................................... 13

3.1.6 Sample Response Body .......................................................................................................... 13

3.2 Retrieve Profile ................................................................................................................ 15 3.2.1 Request URI ............................................................................................................................ 15


3.2.3 Request Header ..................................................................................................................... 15


3.2.5 Response Body ....................................................................................................................... 16


3.3 Disassociate MAC from a profile .................................................................................... 17 3.3.1 Request URI ............................................................................................................................ 17


3.3.3 Request Header ..................................................................................................................... 17


3.3.5 Response Body ....................................................................................................................... 18


3.4 Get Devices for a Profile ................................................................................................. 19 3.4.1 Request URI ............................................................................................................................ 19


3.4.3 Request Header ..................................................................................................................... 19



2

3.4.1 Response Body ....................................................................................................................... 20


4 Appendix .............................................................................................................................................. 21

4.1 Request Headers .............................................................................................................. 21 4.2 Error codes:...................................................................................................................... 21 4.3 Generic Exceptions: ......................................................................................................... 21


3

1 Introduction

This document aims in detailing the API specifications for the CDA (Cisco Device Activations)

Rest services to setup redirection for your devices.

2 Service Authentication All the services are currently exposed through the mule API gateway. This uses OAuth for

service authentication. Access tokens have a lifetime of 1 hour and there is a limit to the number

of tokens that can be generated per day.

The expectation is for the consumers to cache the access tokens and generate them only when

needed.

2.1 First Time Access

Prerequisites:

1. You have an existing cisco.com account. To register go to:

https://idreg.cloudapps.cisco.com/idreg/guestRegistration.do?locale=en_US&exit_url=

2. Your cisco.com account has access on CDA / EDOS web portal

(https://webapps.cisco.com/software/edos/home) as “Distributed Customer” role. If not,

you can request access there by logging in with your cisco.com account.

Note: If you already have an access for different type of role, you can email to cdap-

[email protected] for help. Please make sure you specify your cisco.com user id (could

be different from your email address) when reaching out to support team.

3. You have redirection profile created under Profile Management section of the CDA /

EDOS web portal.

Send an email to “[email protected]” to provide the VIEW and ENTITLE access to the “RC Provisioning” API in production environment.

2.1.1 API Manager Portal

API Portal is used to create client applications, get the client_key and client_secret, and then

associate your client applications to API's.

• API Portal: https://anypoint.mulesoft.com/apiplatform/apx/#/portals

https://idreg.cloudapps.cisco.com/idreg/guestRegistration.do?locale=en_US&exit_url

https://webapps.cisco.com/software/edos/home

mailto:[email protected]

mailto:[email protected]

https://anypoint.mulesoft.com/apiplatform/apx/#/portals


4

2.2 Creating client Applications

1. Select the API under which client application has to be created. In this case,

search for “RC” and from search results, please click on RC Provisioning.


5

2. Click on “Request API access” to create new Application under the API’s.

3. Create a New Application by clicking on New Application button.

4. Fill the Application name, OATH2.0 grant type as “Resource Owner Grant” , select the last checkbox and click on ADD.


6

5. Client Application will be created and will be listed out in API applications list

in DASHBOARD. Once the application is successfully created you will get an email notification with your application name along with client ID/Secret associated with it.


7

6. Application name will be available in drop down.

7. Now select the application you created from the drop down list, accept the terms and then request access to the API.

8. This will ensure that your client application is associated with the API and you can provide client id/secret to your customers to generate an Oauth token and pass it as a header for authorization while accessing your API. Click on ok.


8

9. Customer will be able to see their Client Apps under My Applications tab as

shown below.

10. You can access your Client ID and Client Secret by clicking the app under My

applications. Once you click on your app, you will be able to see the client id and client secret.


9

11. Once the contract is approved, Customer will get a contract approval email. After contract approval, customers will be able to generate Token using Token generation service.

•


10

Service to generate the Token :

HTTP method POST

HOST https://cloudsso.cisco.com

Context path /as/token.oauth2

Query Params grant_type=password&client_id=<clientId>&client_secret=<clientSecret>&username=<userName>&password=<password>

Response {"access_token":"<accessToken>","token_type":"Bearer","expires_in":3599}

URL https://cloudsso.cisco.com/as/token.oauth2?grant_type=password&client_id=<clientId>&client_secret=<clientSecret>&username=<Cisco.com user ID>&password=<Cisco.com password>

3 API Requirements

3.1 Assign Mac Address

This service will be used to assign the mac address to a profile name/id.

3.1.1 Request URI

POST https://apx.cisco.com/cdasvcs/api/rc/v1/addMacAddr

POST {"profileName":"test-profile","soldTo":"123456789","shipTo":"234567890","macAddress":["105F4965E096","105F4965E10E","BAC7E70ECA4B","8E4D2D890CD8","B2CEDB5DEE7"], "overrideRequest":"Y"}

https://apx.cisco.com/cdasvcs/api/rc/v1/addMacAddr


11

3.1.2 Query Parameters

Name Description Format Mandatory(Y/N)

profileName Profile to assign String

Y

soldTo Sold to associated to the macaddress .It can be

passed as blank for Distributed Customer.

String

N

shipTo Ship To associated to the macaddress. It can be

passed as blank for Distributed Customer.

String N

macAddress Mac to which profile needs to be assigned.

List

Y

overrideRequest Enter “Y” to map existing mac address to a different profile. Enter “N” or blank to add the Mac Addresses

String N

3.1.3 Request Header

Please refer Request Headers.

3.1.4 Response Attributes

Name Value Place Holder Format Description

statusCode statusCode SUCCESS Give the status of request processing if it succeeded or

failed. The status will be SUCCESS if all macaddresses

are mapped .The status will be PARTIAL SUCCESS if we are


12

PARTIALSUCCESS able to map at least one map macaddress and at least one mac address is not mapped.

FAILURE

statusMessage statusMessage MACADDRESS MAPPED Macaddress is successfully mapped to a profile.

NO VALID MACADDRESS FOR MAPPING

There are no valid macadresses to map to a profile. Check “macStatusList” for details.

INVALID PROFILE NAME Entered profile name is invalid.

INVALID SETUP Entered sold to, ship to, pid combination is Invalid.

FAILED TO MAP MACADDRESS

Failed to map macaddress due to internal error. Please try again or open a case with Support.

INVALID USER User does not have access to Mac address management screen.

macStatusList

Returns the status of each individual macaddress.

Status <limit 1000 characters>

VALID It is a valid Macaddress and can be mapped to a profile.

INVALID Invalid Macaddress format.

MULTIPLE PID PRESENT

When customer is submitting mac addresses belonging to 2 different PIDS which belong to them. In a request, customer

can submit only the Macs associated to one PID.

MAC ADDRESS NOT AVAILABLE

Macaddress is already mapped to an existing profile of a

different user or is associated to the sales order of a different

organization.

VALID AVAILABLE Mac address has existing profile mapped to logged in

user.

pid <data> Gives the pid associated to the macaddress. If value is ‘NOT AVAILABLE’ then pid is not

available in the system.


13

errMsg INVALID FORMAT Macaddress is in invalid format. It should be 12 hexadecimal character.

Macaddress belong to multiple pid

Uploaded set of macaddress associated to different PIDs.

This MAC Address does not belong to you.



organization.

NA No Errors

profileName <data> Gives the profile name associated to the macaddress.

If value is ‘NOT AVAILABLE’ then macaddress is not

mapped to any profile in the system.

macAddr <data> Macaddress uploaded.

3.1.5 Response Body {

“statusCode”: “<statusCode>”,”statusMessage”:”<statusMessage>”, "macStatusList":[{"status":"<macaddressStatus>","pid":"<pid>","errMsg":"<errorMessage>","profileName":"<profileName>","macAddr":"<macaddress>"},{"status":"<macaddressStatus>","pid":"<pid>","errMsg":"<errorMessa

ge>","profileName":"<profileName>","macAddr":"< macAddress>"}] }

3.1.6 Sample Response Body //Success Response

{ “statusCode”: “SUCCESS”,”statusMessage”:”MAC ADDRESS MAPPED”, "macStatusList":[{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-

profile","macAddr":"105F4965E10E"},{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-profile","macAddr":"8E4D2D890CD8"},{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-profile","macAddr":"B2CEDB5DEE72"},{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-profile","macAddr":"105F4965E096"},{"status":"VALID","pid":"SPA122-RC","errMsg":"","profileName":"test-

profile","macAddr":"BAC7E70ECA4B"}]

}


14


15

3.2 Retrieve Profile

This service will be used to retrieve the profile names associated with the MAC addresses.

3.2.1 Request URI

POST https://apx.cisco.com/cdasvcs/api/rc/v1/fetchProfile

POST {"macAddress":["105F4965E096”,”105F4965E10E”,”BAC7E70ECA4B”,”8E4D2D890CD8”,”B2CEDB5DEE7"]}



macAddress Mac for which profile needs to be obtained

List

Y



3.2.4 Response Attributes Name Value Place Holder Format Description


failed. FAILURE

statusMessage statusMessage INVALID USER User does not have access to Mac address management

screen.

macStatusList

Returns the status of each individual macaddress

uploaded.

status <limit 1000 characters>

VALID It is a valid Macaddress and can be mapped to a profile.





organization.

https://apx.cisco.com/cdasvcs/api/rc/v1/fetchProfile


16


This Mac address does not belong to you.



organization.

NA No Errors

profileName <data> Gives the profile name associated to the macaddress.

If value is ‘NOT AVAILABLE’ then macaddress is not

mapped to any profile in the system.


3.2.5 Response Body {“statusCode”:”<statusCode>”,statusMessage":"<statusMessage>","macStatusList":[{"status":"<macaddressStatus>","errMsg":"<errorMessage>","profileName":"<profileName>","macAddr":"<macaddress>"},{"status":"<macaddressStatus>”,”errMsg":"<errorMessage>","profileName":"<profileName>","macAddr":"< macAddress>"}]

}


{ “statusCode”:”SUCCESS”,"macStatusList":[{"status":"VALID","errMsg":"NA","profileName":"test-profile","macAddr":"105F4965E10E"},{"status":"VALID","errMsg":"NA","profileName":"test-profile","macAddr":"8E4D2D890CD8"},{"status":"VALID”,"errMsg":"","profileName":"test-

profile","macAddr":"B2CEDB5DEE72"},{"status":"VALID,"errMsg":"NA","profileName":"test-profile","macAddr":"105F4965E096"},{"status":"VALID”,"errMsg":"","profileName":"test-

profile","macAddr":"BAC7E70ECA4B"}]

}

//Failure Response

{"statusCode":"FAILURE","statusMessage":"INVALID USER"}


17

3.3 Disassociate MAC from a profile This service will be used to disassociate the macaddresses from the profile.

3.3.1 Request URI

POST https://apx.cisco.com/cdasvcs/api/rc/v1/disconnectMac

POST {"macAddress":["105F4965E096”,”105F4965E10E”,”BAC7E70ECA4B”,”8E4D2D890CD8”,”B2CEDB5DEE7"]}



macAddress Mac which needs to be disassociated from the

profile

List

Y






failed. The status will be SUCCESS if all macaddresses are disassociated .The status

will be PARTIAL SUCCESS if we are able to disassociate at least

one map macaddress and at least one mac address is not

disassociated.

PARTIALSUCCESS

FAILURE


screen.

NO VALID MACADDRESS FOR DISASSOCIATING

There are no valid macaddress for disassociating.

MACADDRESS DISASSOCIATED

Mac Address has been disassociated.

https://apx.cisco.com/cdasvcs/api/rc/v1/disconnectMac


18

FAILED TO DISASSOCIATE MACADDRESS

Failed to disassociate mac address due to any error.

macStatusList

Returns the status of each individual macaddress

uploaded.

status <limit 1000 characters>

VALID It is a valid Macaddress and can be disassociated.



Macaddress is new and not available or already mapped to

an existing profile of a different user or is associated

to the sales order of a different organization.


This Mac address does not belong to you.

Macaddress is new and not available or already mapped to

an existing profile of a different user or is associated

to the sales order of a different organization.

NA No Errors


3.3.5 Response Body {“statusCode”:”<statusCode>”,”statusMessage":"<statusMessage>","macStatusList":[{"status":"<macaddressStatus>","errMsg":"<errorMessage>","macAddr":"<macaddress>"},{"status":"<macaddressStatus>”,”errMsg":"<errorMessage>","macAddr":"< macAddress>"}]

}


{“statusCode”:”SUCCESS”,”statusMessage”:” MACADDRESS

DISASSOCIATED”,"macStatusList":[{"status":"VALID","errMsg":"NA","macAddr":"105F4965E10E"},{"status":"VALID","errMsg":"NA","macAddr":"8E4D2D890CD8"}}

//Failure Response

{"statusCode":"FAILURE","statusMessage":"INVALID USER"}


19

3.4 Get Devices for a Profile This service will be used to get a list of devices using the profile.

3.4.1 Request URI

POST https://apx.cisco.com/cdasvcs/api/rc/v1/getMacs

POST {"profileName": "test-profile","rowFrom":5, "rowTo":10}



profileName Profile Name for which device list is required

String

Y

rowFrom The record from which data needs to be fetched.If input value is not given it will take rowFrom as 1.

int N

rowTo The record to which data needs to be fetched.If

input value is not given it will be set to

rowFrom+4999 by default.

int N





statusCode statusCode SUCCESS The status will be SUCCESS if macaddress is fetched .The

status will be FAILURE in case device list is not fetched due to

errors.

FAILURE


screen.

INVALID PROFILE NAME Entered profile name is invalid.

https://apx.cisco.com/cdasvcs/api/rc/v1/getMacs


20

NO DEVICES MAPPED TO THE PROFILE

There are no macaddress associated to the profile and

user.

DEVICE LIST FETCHED List of macaddress associated to the profile is fetched.

deviceCount deviceCount <data> Count of macaddress accosiate to the profile and user.

macActivationStatusList

Returns the list of macaddress and activation status.

macAddr <data> Macaddress associated to the profile.

status ACTIVE Device is activated.

INACTIVE Device is not activated.

activationDate <data> Date on which device was activate. Will be “NA” if device

is not activated.

3.4.1 Response Body {“statusCode”:”<statusCode>”,”statusMessage":"<statusMessage>", “deviceCount”:<deviceCount>,“macActivationStatusList":[{"status":"<activationStatus>",”activationDate”:”<activationDate>”,"macAddr":"<macaddress>"},{"status":"<activationStatus>”,”activationDate”:”<activationDate>”,”macAddr":"< macAddress>"}] }


{"statusCode":"SUCCESS","statusMessage":"DEVICE LIST FETCHED","macActivationStatusList":[{"status":"ACTIVE","activationDate":"11/08/2016 11:34:10.965809 AM","macAddr":"AC7E8A59A122"},{"status":"ACTIVE","activationDate":"10/31/2016 07:09:06.376282 AM","macAddr":"AC7E8A59AEEA"},{"status":"ACTIVE","activationDate":"11/08/2016 12:47:42.839884 PM","macAddr":"AC7E8A59AD18"},{"status":"ACTIVE","activationDate":"11/01/2016 06:56:13.252189 AM","macAddr":"AC7E8A59AFA4"},{"status":"ACTIVE","activationDate":"08/25/2016 07:51:13.208035 AM","macAddr":"547C6946B542"},{"status":"ACTIVE","activationDate":"08/24/2016 12:58:14.443813 PM","macAddr":"547C6946B55C"}],"deviceCount":73874}

//Failure Response

{"statusCode":"FAILURE","statusMessage":"INVALID PROFILE NAME","deviceCount":0}


21

4 Appendix

4.1 Request Headers

Name Value Description Format

Authorization Bearer <token> It is the access token generated after client

authentication

Required.

It should be in the format of

“Bearer” followed by

token

Content-Type: application/json Content type

4.2 Error codes:

Message Message Code Entity

Error connecting to server. Please contact administrator

Service failure

Profiles not available If PID contains zero profile while

overriding

4.3 Generic Exceptions:

Http Status Code Message Description

<Not Authorized>

If token has expired

. Each token has a

validity of 3599

secs.

500 {

"status": "FAILED",

"messageCode": "RCProvisioning-GENERIC-

ERR-500",

"message": "Error Processing Your Request,

please try later",

"data": null

When service is

down


22

}

405 {

"status": "FAILED",


ERR-405",

"message": "Method not allowed",

"data": null

}

When resource is

not supporting the

http request

method

415 {

"status": "FAILED",


ERR-415",

"message": "Unsupported media type",

"data": null

}

When media type is

not supported

406 {

"status": "FAILED",


ERR-406",

"message": "Not acceptable",

"data": null

}

When response

type is not

matching with

header request

accept type

400 {

"status": "FAILED",


ERR-400",

"message": "Bad request",

"data": null

}

When request is

not meeting the

input criteria

404 {

"status": "FAILED",


ERR-404",

"message": "Resource not found",

When URL is not

correct


23

"data": null

}

cisco device activations rc provisioning api · all the services are currently exposed through the...

Documents