Embed Size (px)
Citation preview
RiverbedCascadeProfilerCommonRESTAPIv10CopyrightcopyRiverbedTechnologyInc2017
CreatedOct262017at0410PM
23333333334567779
101212141516181921212223232424252525
Contents
ContentsOverview
OverviewSSL
CiphersCertificateExamplesKnownIssues
BASICAuthenticationSamplePHPscriptforBASICauthenticationSamplePythonscriptforBASICauthenticationSamplePerlscriptforBASICauthenticationSampleNetCscriptforBASICauthenticationSampleCURLcommand(BASICauthentication)SampleWGETcommand(BASICauthentication)SESSION(Cookie)authenticationSamplePHPscriptforSESSION(Cookie)authenticationSamplePythonscriptforSESSION(Cookie)authenticationSamplePerlscriptforSESSION(Cookie)authenticationSampleNetCscriptforSESSION(Cookie)authenticationOAuth20authenticationSamplePHPscriptforOAuth20authenticationSamplePythonscriptforOAuth20authenticationSamplePerlscriptforOAuth20authenticationSampleNetCscriptforOAuth20authentication
ResourcesServicesListservicesAuth_infoGetauthenticationinfoLoginLoginOauthGetOAuthtokenOauthGetOauthcodeimplicittokenPingPingLogoutLogoutInfoGetinfo
ErrorCodes
2
Overview
OverviewThe documentation pages in this section describe the RESTful APIs included with Cascade Profiler and Cascade Express products It isassumed that the reader has practical knowledge of RESTful APIs so the documentation does not go into detail about what REST isand how to use it Instead the documentation focuses on what data can be accessed and how to access it
The primary focus of the current version of the API is on providing access to common data The following information can be accessedvia the API
System information (serial number model etc)Information and resources for authenticating (login logout oauth 20 etc)
Details about REST resources can be found in the Resources section
SSLAll communication to the profiler is SSL encrypted on Port 443 There is no support for access to the profiler on the standard HTTP port80
CiphersThe ciphers supported by the Profiler may change depending on security setting (eg FIPS mode) Any client when initiating a requestmust include one or more ciphers available in the Profilers configured list Otherwise the client will receive an SSL error indicating thatthere is no cipher overlap and will be unable to connect
CertificateThe profiler by default uses a self-signed certificate for SSL communication The client should be able to handle this by permitting self-signed certificates
ExamplesUsing the curl command line client to request the services resource on a non-FIPS box The -k switch is used to allow the self-signedcertificate and a cipher suite (SSL v3) is provided
curl -k -3 httpshostname443apicommon10services
Using the curl command line client to request the services resource on a FIPS box An explicit cipher is selected
curl --ciphers rsa_aes_256_sha -k httpshostname443apicommon10services
Known IssuesSome clients such as Curl (both as a library and a command line executable) do not support both an explicit cipher list and a ciphersuite The following command will fail on a FIPS Profiler
curl --ciphers rsa_aes_256_sha -3 -k httpshostname443apicommon10services
This is because the cipher suite (-3) overrides the --ciphers argument Clients with this issue will receive a no cipher overlap error evenif they have explicitly provided a cipher that is known to be FIPS compliant
BASIC AuthenticationFor BASIC authentication the request header Authorization must be set to a base64-encoded string of usernamepassword
If the Authorization header is not provided the WWW-Authenticate response header is returned Basic authentication has a built-insupport in various tools Refer to the coding examples
Example of client request to protected resource using Basic Authentication
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Basic YWRtaW46YWRtaW4=
Server response
HTTP11 204 OK
Sample PHP script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
ltphp
define(HOST127001)IPaddressofProfilerdefine(BASIC_AUTHadminadmin)
HTTPGETfunctiondo_GET($urlamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_HTTPAUTHCURLAUTH_BASIC)curl_setopt($curlCURLOPT_USERPWDBASIC_AUTH)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Acceptapplicationjson))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Pingtotestbasicauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$info)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001BASIC_AUTH=adminadmin
Libfunctions
defdo_GET(url)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=AuthorizationBasicsbase64b64encode(BASIC_AUTH)Content-Length0Acceptapplicationjson
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Pingtotestbasicauthentication
url=httpssapiprofiler10pingHOSTprintGETsurl
outputinfo=do_GET(url)
if(info[status]==204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
useconstantHOST=gt127001useconstantLOGIN=gtadminuseconstantPASSWORD=gtadmin
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
sub_request($)my$req=shift
$req-gtheader(Accept=gtapplicationjson)$req-gtauthorization_basic(LOGINPASSWORD)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subGET($)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)return_request($req)
Pingtotestbasicauthentication
printGETapiprofiler10pingnmy$response=GET(apiprofiler10ping)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientclassProgramstaticstringBASIC_AUTH=adminadmin
callbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrueX509Certificate2certv2=newX509Certificate2(cert)if(certv2GetNameInfo(X509NameTypeSimpleNametrue)==wwwriverbedcom)returntrue
returnfalse
privatestaticstringBase64Encode(stringtoEncode)
privatestaticstringBase64Encode(stringtoEncode)byte[]toEncodeAsBytes=SystemTextASCIIEncodingASCIIGetBytes(toEncode)returnSystemConvertToBase64String(toEncodeAsBytes)
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apiprofiler10ping
PingtotestbeaicauthenticationConsoleWriteLine(GET+requestUrl)
PosttorunthereportHttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestrequestHeadersAdd(AuthorizationBasic+Base64Encode(BASIC_AUTH))requestContentType=applicationjsonrequestMethod=WebRequestMethodsHttpGetrequestContentLength=0using(varresponse=requestGetResponse()asHttpWebResponse)if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
catch(Exceptione)ConsoleWriteLine(eMessage)
Sample CURL command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
curl --user usernamepassword httpshostapiprofiler10ping -k
Sample WGET command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
wget --http-user username --http-password password httpshostapiprofiler10ping --no-check-certificate
SESSION (Cookie) authenticationIn order to use the SESSION (Cookie) authentication a session ID must be generated The session ID can then be used to accessprotected resources To generate a session ID the client must send a POST request with username password and optionally purposeThe API supports three different methods of input x-www-form-urlencoded JSON and XML
Client request using x-www-form-urlencoded input
POST apicommon10loginHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
username=usernameamppassword=passwordamppurpose=script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using JSON input
POST apicommon10loginHost 127001Content-Type applicationjsonAccept applicationjson
username username password password purpose script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using XML input
POST apicommon10loginHost 127001Content-Type textxmlAccept textxml
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
ltlogin username=user password=pass purpose=UI login gt
The client must include the Cookie header when accessing authenticated resources The session (cookie) expiration rules are the sameas the ones used in the GUI of the product The rules can be changed from the Log-in Settings page
Client request to protected resource using the session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204 OK
Client request to protected resource using expiredinvalid session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 401 AUTH_INVALID_SESSIONContent-Type applicationjson
error_id AUTH_INVALID_SESSION error_text Session ID is invalid
To end a previously started session the client sends a GET request to logout including a Cookie header with the session ID
Client request to end a previously started session
GET apicommon10logoutHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204
Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
ltphp
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-TypeapplicationjsonAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$session_key$session_idamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonCookie$session_key=$session_id))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttocreatesessionid
$login_data=array(username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication)$url=httpsHOSTapicommon10login$output=do_POST($urljson_encode($login_data)$info)
if($info[http_code]=200)echoLoginFailednecho$outputexit(1)
$data=json_decode($output1)$session_key=$data[session_key]$session_id=$data[session_id]
echoLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$session_key$session_id$info)
if($info[http_code]==204)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
23333333334567779
101212141516181921212223232424252525
Contents
ContentsOverview
OverviewSSL
CiphersCertificateExamplesKnownIssues
BASICAuthenticationSamplePHPscriptforBASICauthenticationSamplePythonscriptforBASICauthenticationSamplePerlscriptforBASICauthenticationSampleNetCscriptforBASICauthenticationSampleCURLcommand(BASICauthentication)SampleWGETcommand(BASICauthentication)SESSION(Cookie)authenticationSamplePHPscriptforSESSION(Cookie)authenticationSamplePythonscriptforSESSION(Cookie)authenticationSamplePerlscriptforSESSION(Cookie)authenticationSampleNetCscriptforSESSION(Cookie)authenticationOAuth20authenticationSamplePHPscriptforOAuth20authenticationSamplePythonscriptforOAuth20authenticationSamplePerlscriptforOAuth20authenticationSampleNetCscriptforOAuth20authentication
ResourcesServicesListservicesAuth_infoGetauthenticationinfoLoginLoginOauthGetOAuthtokenOauthGetOauthcodeimplicittokenPingPingLogoutLogoutInfoGetinfo
ErrorCodes
2
Overview
OverviewThe documentation pages in this section describe the RESTful APIs included with Cascade Profiler and Cascade Express products It isassumed that the reader has practical knowledge of RESTful APIs so the documentation does not go into detail about what REST isand how to use it Instead the documentation focuses on what data can be accessed and how to access it
The primary focus of the current version of the API is on providing access to common data The following information can be accessedvia the API
System information (serial number model etc)Information and resources for authenticating (login logout oauth 20 etc)
Details about REST resources can be found in the Resources section
SSLAll communication to the profiler is SSL encrypted on Port 443 There is no support for access to the profiler on the standard HTTP port80
CiphersThe ciphers supported by the Profiler may change depending on security setting (eg FIPS mode) Any client when initiating a requestmust include one or more ciphers available in the Profilers configured list Otherwise the client will receive an SSL error indicating thatthere is no cipher overlap and will be unable to connect
CertificateThe profiler by default uses a self-signed certificate for SSL communication The client should be able to handle this by permitting self-signed certificates
ExamplesUsing the curl command line client to request the services resource on a non-FIPS box The -k switch is used to allow the self-signedcertificate and a cipher suite (SSL v3) is provided
curl -k -3 httpshostname443apicommon10services
Using the curl command line client to request the services resource on a FIPS box An explicit cipher is selected
curl --ciphers rsa_aes_256_sha -k httpshostname443apicommon10services
Known IssuesSome clients such as Curl (both as a library and a command line executable) do not support both an explicit cipher list and a ciphersuite The following command will fail on a FIPS Profiler
curl --ciphers rsa_aes_256_sha -3 -k httpshostname443apicommon10services
This is because the cipher suite (-3) overrides the --ciphers argument Clients with this issue will receive a no cipher overlap error evenif they have explicitly provided a cipher that is known to be FIPS compliant
BASIC AuthenticationFor BASIC authentication the request header Authorization must be set to a base64-encoded string of usernamepassword
If the Authorization header is not provided the WWW-Authenticate response header is returned Basic authentication has a built-insupport in various tools Refer to the coding examples
Example of client request to protected resource using Basic Authentication
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Basic YWRtaW46YWRtaW4=
Server response
HTTP11 204 OK
Sample PHP script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
ltphp
define(HOST127001)IPaddressofProfilerdefine(BASIC_AUTHadminadmin)
HTTPGETfunctiondo_GET($urlamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_HTTPAUTHCURLAUTH_BASIC)curl_setopt($curlCURLOPT_USERPWDBASIC_AUTH)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Acceptapplicationjson))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Pingtotestbasicauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$info)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001BASIC_AUTH=adminadmin
Libfunctions
defdo_GET(url)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=AuthorizationBasicsbase64b64encode(BASIC_AUTH)Content-Length0Acceptapplicationjson
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Pingtotestbasicauthentication
url=httpssapiprofiler10pingHOSTprintGETsurl
outputinfo=do_GET(url)
if(info[status]==204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
useconstantHOST=gt127001useconstantLOGIN=gtadminuseconstantPASSWORD=gtadmin
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
sub_request($)my$req=shift
$req-gtheader(Accept=gtapplicationjson)$req-gtauthorization_basic(LOGINPASSWORD)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subGET($)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)return_request($req)
Pingtotestbasicauthentication
printGETapiprofiler10pingnmy$response=GET(apiprofiler10ping)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientclassProgramstaticstringBASIC_AUTH=adminadmin
callbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrueX509Certificate2certv2=newX509Certificate2(cert)if(certv2GetNameInfo(X509NameTypeSimpleNametrue)==wwwriverbedcom)returntrue
returnfalse
privatestaticstringBase64Encode(stringtoEncode)
privatestaticstringBase64Encode(stringtoEncode)byte[]toEncodeAsBytes=SystemTextASCIIEncodingASCIIGetBytes(toEncode)returnSystemConvertToBase64String(toEncodeAsBytes)
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apiprofiler10ping
PingtotestbeaicauthenticationConsoleWriteLine(GET+requestUrl)
PosttorunthereportHttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestrequestHeadersAdd(AuthorizationBasic+Base64Encode(BASIC_AUTH))requestContentType=applicationjsonrequestMethod=WebRequestMethodsHttpGetrequestContentLength=0using(varresponse=requestGetResponse()asHttpWebResponse)if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
catch(Exceptione)ConsoleWriteLine(eMessage)
Sample CURL command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
curl --user usernamepassword httpshostapiprofiler10ping -k
Sample WGET command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
wget --http-user username --http-password password httpshostapiprofiler10ping --no-check-certificate
SESSION (Cookie) authenticationIn order to use the SESSION (Cookie) authentication a session ID must be generated The session ID can then be used to accessprotected resources To generate a session ID the client must send a POST request with username password and optionally purposeThe API supports three different methods of input x-www-form-urlencoded JSON and XML
Client request using x-www-form-urlencoded input
POST apicommon10loginHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
username=usernameamppassword=passwordamppurpose=script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using JSON input
POST apicommon10loginHost 127001Content-Type applicationjsonAccept applicationjson
username username password password purpose script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using XML input
POST apicommon10loginHost 127001Content-Type textxmlAccept textxml
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
ltlogin username=user password=pass purpose=UI login gt
The client must include the Cookie header when accessing authenticated resources The session (cookie) expiration rules are the sameas the ones used in the GUI of the product The rules can be changed from the Log-in Settings page
Client request to protected resource using the session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204 OK
Client request to protected resource using expiredinvalid session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 401 AUTH_INVALID_SESSIONContent-Type applicationjson
error_id AUTH_INVALID_SESSION error_text Session ID is invalid
To end a previously started session the client sends a GET request to logout including a Cookie header with the session ID
Client request to end a previously started session
GET apicommon10logoutHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204
Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
ltphp
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-TypeapplicationjsonAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$session_key$session_idamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonCookie$session_key=$session_id))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttocreatesessionid
$login_data=array(username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication)$url=httpsHOSTapicommon10login$output=do_POST($urljson_encode($login_data)$info)
if($info[http_code]=200)echoLoginFailednecho$outputexit(1)
$data=json_decode($output1)$session_key=$data[session_key]$session_id=$data[session_id]
echoLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$session_key$session_id$info)
if($info[http_code]==204)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
Overview
OverviewThe documentation pages in this section describe the RESTful APIs included with Cascade Profiler and Cascade Express products It isassumed that the reader has practical knowledge of RESTful APIs so the documentation does not go into detail about what REST isand how to use it Instead the documentation focuses on what data can be accessed and how to access it
The primary focus of the current version of the API is on providing access to common data The following information can be accessedvia the API
System information (serial number model etc)Information and resources for authenticating (login logout oauth 20 etc)
Details about REST resources can be found in the Resources section
SSLAll communication to the profiler is SSL encrypted on Port 443 There is no support for access to the profiler on the standard HTTP port80
CiphersThe ciphers supported by the Profiler may change depending on security setting (eg FIPS mode) Any client when initiating a requestmust include one or more ciphers available in the Profilers configured list Otherwise the client will receive an SSL error indicating thatthere is no cipher overlap and will be unable to connect
CertificateThe profiler by default uses a self-signed certificate for SSL communication The client should be able to handle this by permitting self-signed certificates
ExamplesUsing the curl command line client to request the services resource on a non-FIPS box The -k switch is used to allow the self-signedcertificate and a cipher suite (SSL v3) is provided
curl -k -3 httpshostname443apicommon10services
Using the curl command line client to request the services resource on a FIPS box An explicit cipher is selected
curl --ciphers rsa_aes_256_sha -k httpshostname443apicommon10services
Known IssuesSome clients such as Curl (both as a library and a command line executable) do not support both an explicit cipher list and a ciphersuite The following command will fail on a FIPS Profiler
curl --ciphers rsa_aes_256_sha -3 -k httpshostname443apicommon10services
This is because the cipher suite (-3) overrides the --ciphers argument Clients with this issue will receive a no cipher overlap error evenif they have explicitly provided a cipher that is known to be FIPS compliant
BASIC AuthenticationFor BASIC authentication the request header Authorization must be set to a base64-encoded string of usernamepassword
If the Authorization header is not provided the WWW-Authenticate response header is returned Basic authentication has a built-insupport in various tools Refer to the coding examples
Example of client request to protected resource using Basic Authentication
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Basic YWRtaW46YWRtaW4=
Server response
HTTP11 204 OK
Sample PHP script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
ltphp
define(HOST127001)IPaddressofProfilerdefine(BASIC_AUTHadminadmin)
HTTPGETfunctiondo_GET($urlamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_HTTPAUTHCURLAUTH_BASIC)curl_setopt($curlCURLOPT_USERPWDBASIC_AUTH)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Acceptapplicationjson))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Pingtotestbasicauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$info)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001BASIC_AUTH=adminadmin
Libfunctions
defdo_GET(url)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=AuthorizationBasicsbase64b64encode(BASIC_AUTH)Content-Length0Acceptapplicationjson
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Pingtotestbasicauthentication
url=httpssapiprofiler10pingHOSTprintGETsurl
outputinfo=do_GET(url)
if(info[status]==204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
useconstantHOST=gt127001useconstantLOGIN=gtadminuseconstantPASSWORD=gtadmin
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
sub_request($)my$req=shift
$req-gtheader(Accept=gtapplicationjson)$req-gtauthorization_basic(LOGINPASSWORD)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subGET($)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)return_request($req)
Pingtotestbasicauthentication
printGETapiprofiler10pingnmy$response=GET(apiprofiler10ping)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientclassProgramstaticstringBASIC_AUTH=adminadmin
callbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrueX509Certificate2certv2=newX509Certificate2(cert)if(certv2GetNameInfo(X509NameTypeSimpleNametrue)==wwwriverbedcom)returntrue
returnfalse
privatestaticstringBase64Encode(stringtoEncode)
privatestaticstringBase64Encode(stringtoEncode)byte[]toEncodeAsBytes=SystemTextASCIIEncodingASCIIGetBytes(toEncode)returnSystemConvertToBase64String(toEncodeAsBytes)
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apiprofiler10ping
PingtotestbeaicauthenticationConsoleWriteLine(GET+requestUrl)
PosttorunthereportHttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestrequestHeadersAdd(AuthorizationBasic+Base64Encode(BASIC_AUTH))requestContentType=applicationjsonrequestMethod=WebRequestMethodsHttpGetrequestContentLength=0using(varresponse=requestGetResponse()asHttpWebResponse)if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
catch(Exceptione)ConsoleWriteLine(eMessage)
Sample CURL command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
curl --user usernamepassword httpshostapiprofiler10ping -k
Sample WGET command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
wget --http-user username --http-password password httpshostapiprofiler10ping --no-check-certificate
SESSION (Cookie) authenticationIn order to use the SESSION (Cookie) authentication a session ID must be generated The session ID can then be used to accessprotected resources To generate a session ID the client must send a POST request with username password and optionally purposeThe API supports three different methods of input x-www-form-urlencoded JSON and XML
Client request using x-www-form-urlencoded input
POST apicommon10loginHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
username=usernameamppassword=passwordamppurpose=script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using JSON input
POST apicommon10loginHost 127001Content-Type applicationjsonAccept applicationjson
username username password password purpose script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using XML input
POST apicommon10loginHost 127001Content-Type textxmlAccept textxml
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
ltlogin username=user password=pass purpose=UI login gt
The client must include the Cookie header when accessing authenticated resources The session (cookie) expiration rules are the sameas the ones used in the GUI of the product The rules can be changed from the Log-in Settings page
Client request to protected resource using the session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204 OK
Client request to protected resource using expiredinvalid session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 401 AUTH_INVALID_SESSIONContent-Type applicationjson
error_id AUTH_INVALID_SESSION error_text Session ID is invalid
To end a previously started session the client sends a GET request to logout including a Cookie header with the session ID
Client request to end a previously started session
GET apicommon10logoutHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204
Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
ltphp
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-TypeapplicationjsonAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$session_key$session_idamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonCookie$session_key=$session_id))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttocreatesessionid
$login_data=array(username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication)$url=httpsHOSTapicommon10login$output=do_POST($urljson_encode($login_data)$info)
if($info[http_code]=200)echoLoginFailednecho$outputexit(1)
$data=json_decode($output1)$session_key=$data[session_key]$session_id=$data[session_id]
echoLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$session_key$session_id$info)
if($info[http_code]==204)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
ltphp
define(HOST127001)IPaddressofProfilerdefine(BASIC_AUTHadminadmin)
HTTPGETfunctiondo_GET($urlamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_HTTPAUTHCURLAUTH_BASIC)curl_setopt($curlCURLOPT_USERPWDBASIC_AUTH)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Acceptapplicationjson))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Pingtotestbasicauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$info)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001BASIC_AUTH=adminadmin
Libfunctions
defdo_GET(url)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=AuthorizationBasicsbase64b64encode(BASIC_AUTH)Content-Length0Acceptapplicationjson
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Pingtotestbasicauthentication
url=httpssapiprofiler10pingHOSTprintGETsurl
outputinfo=do_GET(url)
if(info[status]==204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
useconstantHOST=gt127001useconstantLOGIN=gtadminuseconstantPASSWORD=gtadmin
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
sub_request($)my$req=shift
$req-gtheader(Accept=gtapplicationjson)$req-gtauthorization_basic(LOGINPASSWORD)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subGET($)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)return_request($req)
Pingtotestbasicauthentication
printGETapiprofiler10pingnmy$response=GET(apiprofiler10ping)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientclassProgramstaticstringBASIC_AUTH=adminadmin
callbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrueX509Certificate2certv2=newX509Certificate2(cert)if(certv2GetNameInfo(X509NameTypeSimpleNametrue)==wwwriverbedcom)returntrue
returnfalse
privatestaticstringBase64Encode(stringtoEncode)
privatestaticstringBase64Encode(stringtoEncode)byte[]toEncodeAsBytes=SystemTextASCIIEncodingASCIIGetBytes(toEncode)returnSystemConvertToBase64String(toEncodeAsBytes)
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apiprofiler10ping
PingtotestbeaicauthenticationConsoleWriteLine(GET+requestUrl)
PosttorunthereportHttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestrequestHeadersAdd(AuthorizationBasic+Base64Encode(BASIC_AUTH))requestContentType=applicationjsonrequestMethod=WebRequestMethodsHttpGetrequestContentLength=0using(varresponse=requestGetResponse()asHttpWebResponse)if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
catch(Exceptione)ConsoleWriteLine(eMessage)
Sample CURL command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
curl --user usernamepassword httpshostapiprofiler10ping -k
Sample WGET command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
wget --http-user username --http-password password httpshostapiprofiler10ping --no-check-certificate
SESSION (Cookie) authenticationIn order to use the SESSION (Cookie) authentication a session ID must be generated The session ID can then be used to accessprotected resources To generate a session ID the client must send a POST request with username password and optionally purposeThe API supports three different methods of input x-www-form-urlencoded JSON and XML
Client request using x-www-form-urlencoded input
POST apicommon10loginHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
username=usernameamppassword=passwordamppurpose=script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using JSON input
POST apicommon10loginHost 127001Content-Type applicationjsonAccept applicationjson
username username password password purpose script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using XML input
POST apicommon10loginHost 127001Content-Type textxmlAccept textxml
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
ltlogin username=user password=pass purpose=UI login gt
The client must include the Cookie header when accessing authenticated resources The session (cookie) expiration rules are the sameas the ones used in the GUI of the product The rules can be changed from the Log-in Settings page
Client request to protected resource using the session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204 OK
Client request to protected resource using expiredinvalid session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 401 AUTH_INVALID_SESSIONContent-Type applicationjson
error_id AUTH_INVALID_SESSION error_text Session ID is invalid
To end a previously started session the client sends a GET request to logout including a Cookie header with the session ID
Client request to end a previously started session
GET apicommon10logoutHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204
Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
ltphp
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-TypeapplicationjsonAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$session_key$session_idamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonCookie$session_key=$session_id))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttocreatesessionid
$login_data=array(username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication)$url=httpsHOSTapicommon10login$output=do_POST($urljson_encode($login_data)$info)
if($info[http_code]=200)echoLoginFailednecho$outputexit(1)
$data=json_decode($output1)$session_key=$data[session_key]$session_id=$data[session_id]
echoLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$session_key$session_id$info)
if($info[http_code]==204)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001BASIC_AUTH=adminadmin
Libfunctions
defdo_GET(url)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=AuthorizationBasicsbase64b64encode(BASIC_AUTH)Content-Length0Acceptapplicationjson
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Pingtotestbasicauthentication
url=httpssapiprofiler10pingHOSTprintGETsurl
outputinfo=do_GET(url)
if(info[status]==204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
useconstantHOST=gt127001useconstantLOGIN=gtadminuseconstantPASSWORD=gtadmin
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
sub_request($)my$req=shift
$req-gtheader(Accept=gtapplicationjson)$req-gtauthorization_basic(LOGINPASSWORD)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subGET($)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)return_request($req)
Pingtotestbasicauthentication
printGETapiprofiler10pingnmy$response=GET(apiprofiler10ping)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientclassProgramstaticstringBASIC_AUTH=adminadmin
callbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrueX509Certificate2certv2=newX509Certificate2(cert)if(certv2GetNameInfo(X509NameTypeSimpleNametrue)==wwwriverbedcom)returntrue
returnfalse
privatestaticstringBase64Encode(stringtoEncode)
privatestaticstringBase64Encode(stringtoEncode)byte[]toEncodeAsBytes=SystemTextASCIIEncodingASCIIGetBytes(toEncode)returnSystemConvertToBase64String(toEncodeAsBytes)
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apiprofiler10ping
PingtotestbeaicauthenticationConsoleWriteLine(GET+requestUrl)
PosttorunthereportHttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestrequestHeadersAdd(AuthorizationBasic+Base64Encode(BASIC_AUTH))requestContentType=applicationjsonrequestMethod=WebRequestMethodsHttpGetrequestContentLength=0using(varresponse=requestGetResponse()asHttpWebResponse)if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
catch(Exceptione)ConsoleWriteLine(eMessage)
Sample CURL command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
curl --user usernamepassword httpshostapiprofiler10ping -k
Sample WGET command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
wget --http-user username --http-password password httpshostapiprofiler10ping --no-check-certificate
SESSION (Cookie) authenticationIn order to use the SESSION (Cookie) authentication a session ID must be generated The session ID can then be used to accessprotected resources To generate a session ID the client must send a POST request with username password and optionally purposeThe API supports three different methods of input x-www-form-urlencoded JSON and XML
Client request using x-www-form-urlencoded input
POST apicommon10loginHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
username=usernameamppassword=passwordamppurpose=script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using JSON input
POST apicommon10loginHost 127001Content-Type applicationjsonAccept applicationjson
username username password password purpose script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using XML input
POST apicommon10loginHost 127001Content-Type textxmlAccept textxml
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
ltlogin username=user password=pass purpose=UI login gt
The client must include the Cookie header when accessing authenticated resources The session (cookie) expiration rules are the sameas the ones used in the GUI of the product The rules can be changed from the Log-in Settings page
Client request to protected resource using the session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204 OK
Client request to protected resource using expiredinvalid session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 401 AUTH_INVALID_SESSIONContent-Type applicationjson
error_id AUTH_INVALID_SESSION error_text Session ID is invalid
To end a previously started session the client sends a GET request to logout including a Cookie header with the session ID
Client request to end a previously started session
GET apicommon10logoutHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204
Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
ltphp
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-TypeapplicationjsonAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$session_key$session_idamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonCookie$session_key=$session_id))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttocreatesessionid
$login_data=array(username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication)$url=httpsHOSTapicommon10login$output=do_POST($urljson_encode($login_data)$info)
if($info[http_code]=200)echoLoginFailednecho$outputexit(1)
$data=json_decode($output1)$session_key=$data[session_key]$session_id=$data[session_id]
echoLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$session_key$session_id$info)
if($info[http_code]==204)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
useconstantHOST=gt127001useconstantLOGIN=gtadminuseconstantPASSWORD=gtadmin
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
sub_request($)my$req=shift
$req-gtheader(Accept=gtapplicationjson)$req-gtauthorization_basic(LOGINPASSWORD)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subGET($)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)return_request($req)
Pingtotestbasicauthentication
printGETapiprofiler10pingnmy$response=GET(apiprofiler10ping)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for BASIC authenticationUse the Ping resource to demonstrate BASIC authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientclassProgramstaticstringBASIC_AUTH=adminadmin
callbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrueX509Certificate2certv2=newX509Certificate2(cert)if(certv2GetNameInfo(X509NameTypeSimpleNametrue)==wwwriverbedcom)returntrue
returnfalse
privatestaticstringBase64Encode(stringtoEncode)
privatestaticstringBase64Encode(stringtoEncode)byte[]toEncodeAsBytes=SystemTextASCIIEncodingASCIIGetBytes(toEncode)returnSystemConvertToBase64String(toEncodeAsBytes)
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apiprofiler10ping
PingtotestbeaicauthenticationConsoleWriteLine(GET+requestUrl)
PosttorunthereportHttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestrequestHeadersAdd(AuthorizationBasic+Base64Encode(BASIC_AUTH))requestContentType=applicationjsonrequestMethod=WebRequestMethodsHttpGetrequestContentLength=0using(varresponse=requestGetResponse()asHttpWebResponse)if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
catch(Exceptione)ConsoleWriteLine(eMessage)
Sample CURL command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
curl --user usernamepassword httpshostapiprofiler10ping -k
Sample WGET command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
wget --http-user username --http-password password httpshostapiprofiler10ping --no-check-certificate
SESSION (Cookie) authenticationIn order to use the SESSION (Cookie) authentication a session ID must be generated The session ID can then be used to accessprotected resources To generate a session ID the client must send a POST request with username password and optionally purposeThe API supports three different methods of input x-www-form-urlencoded JSON and XML
Client request using x-www-form-urlencoded input
POST apicommon10loginHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
username=usernameamppassword=passwordamppurpose=script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using JSON input
POST apicommon10loginHost 127001Content-Type applicationjsonAccept applicationjson
username username password password purpose script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using XML input
POST apicommon10loginHost 127001Content-Type textxmlAccept textxml
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
ltlogin username=user password=pass purpose=UI login gt
The client must include the Cookie header when accessing authenticated resources The session (cookie) expiration rules are the sameas the ones used in the GUI of the product The rules can be changed from the Log-in Settings page
Client request to protected resource using the session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204 OK
Client request to protected resource using expiredinvalid session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 401 AUTH_INVALID_SESSIONContent-Type applicationjson
error_id AUTH_INVALID_SESSION error_text Session ID is invalid
To end a previously started session the client sends a GET request to logout including a Cookie header with the session ID
Client request to end a previously started session
GET apicommon10logoutHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204
Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
ltphp
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-TypeapplicationjsonAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$session_key$session_idamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonCookie$session_key=$session_id))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttocreatesessionid
$login_data=array(username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication)$url=httpsHOSTapicommon10login$output=do_POST($urljson_encode($login_data)$info)
if($info[http_code]=200)echoLoginFailednecho$outputexit(1)
$data=json_decode($output1)$session_key=$data[session_key]$session_id=$data[session_id]
echoLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$session_key$session_id$info)
if($info[http_code]==204)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
privatestaticstringBase64Encode(stringtoEncode)byte[]toEncodeAsBytes=SystemTextASCIIEncodingASCIIGetBytes(toEncode)returnSystemConvertToBase64String(toEncodeAsBytes)
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apiprofiler10ping
PingtotestbeaicauthenticationConsoleWriteLine(GET+requestUrl)
PosttorunthereportHttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestrequestHeadersAdd(AuthorizationBasic+Base64Encode(BASIC_AUTH))requestContentType=applicationjsonrequestMethod=WebRequestMethodsHttpGetrequestContentLength=0using(varresponse=requestGetResponse()asHttpWebResponse)if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
catch(Exceptione)ConsoleWriteLine(eMessage)
Sample CURL command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
curl --user usernamepassword httpshostapiprofiler10ping -k
Sample WGET command (BASIC authentication)Use the Ping resource to demonstrate BASIC authentication
wget --http-user username --http-password password httpshostapiprofiler10ping --no-check-certificate
SESSION (Cookie) authenticationIn order to use the SESSION (Cookie) authentication a session ID must be generated The session ID can then be used to accessprotected resources To generate a session ID the client must send a POST request with username password and optionally purposeThe API supports three different methods of input x-www-form-urlencoded JSON and XML
Client request using x-www-form-urlencoded input
POST apicommon10loginHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
username=usernameamppassword=passwordamppurpose=script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using JSON input
POST apicommon10loginHost 127001Content-Type applicationjsonAccept applicationjson
username username password password purpose script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using XML input
POST apicommon10loginHost 127001Content-Type textxmlAccept textxml
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
ltlogin username=user password=pass purpose=UI login gt
The client must include the Cookie header when accessing authenticated resources The session (cookie) expiration rules are the sameas the ones used in the GUI of the product The rules can be changed from the Log-in Settings page
Client request to protected resource using the session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204 OK
Client request to protected resource using expiredinvalid session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 401 AUTH_INVALID_SESSIONContent-Type applicationjson
error_id AUTH_INVALID_SESSION error_text Session ID is invalid
To end a previously started session the client sends a GET request to logout including a Cookie header with the session ID
Client request to end a previously started session
GET apicommon10logoutHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204
Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
ltphp
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-TypeapplicationjsonAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$session_key$session_idamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonCookie$session_key=$session_id))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttocreatesessionid
$login_data=array(username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication)$url=httpsHOSTapicommon10login$output=do_POST($urljson_encode($login_data)$info)
if($info[http_code]=200)echoLoginFailednecho$outputexit(1)
$data=json_decode($output1)$session_key=$data[session_key]$session_id=$data[session_id]
echoLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$session_key$session_id$info)
if($info[http_code]==204)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
POST apicommon10loginHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
username=usernameamppassword=passwordamppurpose=script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using JSON input
POST apicommon10loginHost 127001Content-Type applicationjsonAccept applicationjson
username username password password purpose script XYZ
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
session_key SESSID session_id bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Client request using XML input
POST apicommon10loginHost 127001Content-Type textxmlAccept textxml
Server response
HTTP11 200 OKSet-Cookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
ltlogin username=user password=pass purpose=UI login gt
The client must include the Cookie header when accessing authenticated resources The session (cookie) expiration rules are the sameas the ones used in the GUI of the product The rules can be changed from the Log-in Settings page
Client request to protected resource using the session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204 OK
Client request to protected resource using expiredinvalid session ID
POST apiprofiler10pingHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 401 AUTH_INVALID_SESSIONContent-Type applicationjson
error_id AUTH_INVALID_SESSION error_text Session ID is invalid
To end a previously started session the client sends a GET request to logout including a Cookie header with the session ID
Client request to end a previously started session
GET apicommon10logoutHost 127001Accept applicationjsonCookie SESSID=bfe3c2fd7b53053eecdd54b08c01d6a8d447aa6c15ed8f7523032c5814221ee7
Server response
HTTP11 204
Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
ltphp
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-TypeapplicationjsonAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$session_key$session_idamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonCookie$session_key=$session_id))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttocreatesessionid
$login_data=array(username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication)$url=httpsHOSTapicommon10login$output=do_POST($urljson_encode($login_data)$info)
if($info[http_code]=200)echoLoginFailednecho$outputexit(1)
$data=json_decode($output1)$session_key=$data[session_key]$session_id=$data[session_id]
echoLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$session_key$session_id$info)
if($info[http_code]==204)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
HTTP11 204
Sample PHP script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
ltphp
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-TypeapplicationjsonAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$session_key$session_idamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonCookie$session_key=$session_id))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttocreatesessionid
$login_data=array(username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication)$url=httpsHOSTapicommon10login$output=do_POST($urljson_encode($login_data)$info)
if($info[http_code]=200)echoLoginFailednecho$outputexit(1)
$data=json_decode($output1)$session_key=$data[session_key]$session_id=$data[session_id]
echoLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$session_key$session_id$info)
if($info[http_code]==204)
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
if($info[http_code]==204)echoPingissuccessfulnelseechoPingfailednecho$output
gt
Sample Python script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-TypeapplicationjsonAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlsession_keysession_id)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonCookies=s(session_keysession_id)
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttocreatesessionid
login_data=usernameadminpasswordadminpurposedemonstrateSESSIONauthentication
url=httpssapicommon10loginHOST
outputinfo=do_POST(urljsondumps(login_data))if(info[status]isnot200)printLoginFailedprintoutputsysexit(1)
data=jsonloads(output)session_key=data[session_key]session_id=data[session_id]
printLoginsuccessfuls=s(session_keysession_id)
url=httpssapiprofiler10pingHOST
Pingtotestsessionauthenticationoutputinfo=do_GET(urlsession_keysession_id)
if(info[status]is204)printPingissuccessfulelseprintPingfailedprintoutput
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
Sample Perl script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$API_BASE=https127001
subGET($$$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$session_key=shiftmy$session_id=shift$req-gtheader(Cookie=gt$session_key=$session_id)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(encode_json(shift))
$req-gtheader(Accept=gtapplicationjson)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttocreatesessionid
my$login_data=username=gtadminpassword=gtadminpurpose=gtdemonstrateSESSIONauthentication
my$response=POST(apicommon10login$login_data)
dieLoginFailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$session_key=$data-gtsession_keymy$session_id=$data-gtsession_idprintLoginsuccessful$session_key=$session_idn
Pingtotestsessionauthentication$response=GET(apiprofiler10ping$session_key$session_id)
if($response-gtcode==204)printPingissuccessfulnelseprintPingfailednprint$response-gtdata
Sample NetC script for SESSION (Cookie) authenticationUse the Ping resource to demonstrate SESSION (Cookie) authentication
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509CertificatesusingSystemWebScriptSerialization
namespaceCascadeRestClientpublicclassAuthResultpublicstringsession_keygetsetpublicstringsession_idgetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringrequestUrl=rootUrl+apicommon10loginjson
varjsondata=newusername=adminpassword=adminpurpose=demonstrateSESSIONauthentication
SerializeanomymoustypetojsonJavaScriptSerializerserializer=newJavaScriptSerializer()stringpostData=serializerSerialize(jsondata)
LoginAuthResultrusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostnullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)return
r=ReadResponseltAuthResultgt(response)ConsoleWriteLine(stringFormat(Loginsuccessful0=1rsession_keyrsession_id))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetstringFormat(Cookie0=1rsession_keyrsession_id)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(Pingissuccessful)elseConsoleWriteLine(Pingfailed)LogResponse(response)
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
catch(Exceptione)ConsoleWriteLine(eMessage)
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclassDataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtlttypeparamname=Tgtreturntypelttypeparamgtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=headergtadditionalheaderexceptacceptandcontenttypeltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequestif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=applicationjsonrequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
returnrequestGetResponse()asHttpWebResponse
OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
Client request to generate an OAuth 20 access token
POST apicommon10oauthtokenHost 127001Content-Type applicationx-www-form-urlencodedAccept applicationjson
grant_type=access_codeampassertion=access code here
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
Server response
HTTP11 200 OKContent-Type applicationjson
access_token ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod token_type bearer expires_in 3600
Client request to protected resource using the OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 204 OK
Client request to protected resource using expired OAuth 20 access token
POST apiprofiler10pingHost 127001Accept applicationjsonAuthorization Bearer ewoJIm5vbmNlIjogImY0MmJhZmIiLAoJImF1ZCI6ICJod
Server response
HTTP11 401 AUTH_EXPIRED_TOKENContent-Type applicationjson
error_id AUTH_EXPIRED_TOKEN error_text OAuth access token is expired
Sample PHP script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
ltphp
define(OAUTH_CODEewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9)
define(HOST127001)IPaddressofProfiler
HTTPPOSTfunctiondo_POST($url$stringamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson))curl_setopt($curlCURLOPT_POST1)curl_setopt($curlCURLOPT_POSTFIELDS$string)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
HTTPGETfunctiondo_GET($url$access_tokenamp$info)$curl=curl_init()curl_setopt($curlCURLOPT_URL$url)
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
curl_setopt($curlCURLOPT_URL$url)curl_setopt($curlCURLOPT_SSLVERSION3)curl_setopt($curlCURLOPT_SSL_VERIFYPEERFALSE)curl_setopt($curlCURLOPT_SSL_VERIFYHOST2)curl_setopt($curlCURLOPT_HEADERtrue)curl_setopt($curlCURLOPT_RETURNTRANSFERtrue)curl_setopt($curlCURLOPT_HTTPHEADERarray(AcceptapplicationjsonAuthorizationBearer$access_token))curl_setopt($curlCURLOPT_HTTPGETtrue)$output=curl_exec($curl)$info=curl_getinfo($curl)curl_close($curl)
$headers=substr($output0$info[header_size])$headers=explode(n$headers)$info[headers]=$headers$body=substr($output$info[header_size])return$body
Posttogetaccesstokenbasedontheaccesscode
$url=httpsHOSTapicommon10oauthtoken$output=do_POST($urlgrant_type=access_codeampassertion=OAUTH_CODE$info)
if($info[http_code]=200)echoPosttogetaccesstokenfailednecho$outputexit(1)
$data=json_decode($output1)$access_token=$data[access_token]$expires_in=$data[expires_in]echoPosttogettokenidissuccessfulnToken$access_tokennechoThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$url=httpsHOSTapiprofiler10pingechoGET$urln
$info=array()$output=do_GET($url$access_token$info)
if($info[http_code]==204)echoOAuth20authenticationissuccessfulnelseechoOAuth20authenticationfailednecho$output
gt
Sample Python script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
fromurlparseimporturlparseimportbase64importloggingimporthttplibimportjsonimporttimeimportsys
OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
HOST=127001
Libfunctions
defdo_POST(urlstring)HTTPPOST
conn=httplibHTTPSConnection(HOST443)
headers=Content-Lengthstr(len(string))Content-Typeapplicationx-www-form-urlencodedAcceptapplicationjson
connrequest(POSTurlbody=stringheaders=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
defdo_GET(urlaccess_token)HTTPGET
conn=httplibHTTPSConnection(HOST443)
headers=Content-Length0Content-TypeapplicationjsonAcceptapplicationjsonAuthorizationBearersaccess_token
connrequest(GETurlbody=headers=headers)
res=conngetresponse()
info=statusresstatusheadersresgetheaders()
data=resread()connclose()returndatainfo
Posttogetaccesstokenbasedontheaccesscode
url=httpssapicommon10oauthtokenHOST
outputinfo=do_POST(urlgrant_type=access_codeampassertion=sOAUTH_CODE)if(info[status]isnot200)printPosttogetaccesstokenfailedprintoutputsysexit(1)
data=jsonloads(output)access_token=data[access_token]expires_in=data[expires_in]
printPosttogettokenidissuccessfulprintTokensaccess_tokenprintThetokenwillexpireinssecondsexpires_in
PingtotestOAuth20authenticationurl=httpssapiprofiler10pingHOSToutputinfo=do_GET(urlaccess_token)
if(info[status]is204)printOAuth20authenticationissuccessfulelseprintOAuth20authenticationfailedprintoutput
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
Sample Perl script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
usrbinperlusestrictusewarnings
useLWPUserAgentuseHTTPRequestuseListMoreUtilsqw(firstidx)useJSONqw(encode_jsondecode_json)
our$ua=LWPUserAgent-gtnew$ua-gtagent(ProfilerScript01)
our$OAUTH_CODE=ewoJIm5vbmNlIjogImFmNTBlOTkxIiwKCSJhdWQiOiAiaHR0cHM6Ly9kZXNvLTEvYXBpL2NvbW1vbi8xLjAvb2F1dGgvdG9rZW4iLAoJImlzcyI6ICJodHRwczovL2Rlc28tMSIsCgkicHJuIjogImFkbWluIiwKCSJqdGkiOiAiMSIsCgkiZXhwIjogIjEzNTY1NTM5NDkiLAoJImlhdCI6ICIxMzUzOTYxOTQ5Igp9
our$API_BASE=https127001
subGET($$)my$req=HTTPRequest-gtnew(GET=gt$API_BASEshift)$req-gtheader(Accept=gtapplicationjson)
my$access_token=shift$req-gtheader(Authorization=gtBearer$access_token)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
subPOST($$)my$req=HTTPRequest-gtnew(POST=gt$API_BASEshift)$req-gtcontent_type(applicationjson)$req-gtcontent(shift)
$req-gtheader(Accept=gtapplicationjson)$req-gtheader(Content-Type=gtapplicationx-www-form-urlencoded)
my$res=$ua-gtrequest($req)
returncode=gt$res-gtcodestatus=gt$res-gtstatus_lineheaders=gt$res-gtheaders()data=gt$res-gtcontent
Posttogetaccesstokenbasedontheaccesscode
my$url=apicommon10oauthtokenmy$response=POST($urlgrant_type=access_codeampassertion=$OAUTH_CODE)
diePosttogetaccesstokenfailedn$response-gtdatanunless$response-gtcode==200
my$data=decode_json($response-gtdata)my$access_token=$data-gtaccess_tokenmy$expires_in=$data-gtexpires_inprintPosttogettokenidissuccessfulnToken$access_tokennprintThetokenwillexpirein$expires_insecondsn
PingtotestOAuth20authentication$response=GET(apiprofiler10ping$access_token)
if($response-gtcode==204)printOAuth20authenticationissuccessfulnelseprintOAuth20authenticationfailednprint$response-gtdata
Sample NetC script for OAuth 20 authenticationIn order to use the OAuth 20 authentication an access code needs to be generated To generate the code
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
Go to the Configuration =gt Account management =gt OAuth Access pageClick the Generate new buttonEnter a description for the access code The description is used for auditing purposesThe system generates an access code Use this in your script
All access to protected resources requires a valid access token To get an access token the client must send a POST request with theaccess code The server will issue an access token that is valid for the next 1 hour and return it in the body of the POST If the clientscript runs for more than 1 hour then it will need to generate another access token when the one that it has expires An expired tokenresults into an error with HTTP code 401 and error_id AUTH_EXPIRED_TOKEN
usingSystemusingSystemCollectionsGenericusingSystemNetusingSystemRuntimeSerializationJsonusingSystemTextusingSystemIOusingSystemNetSecurityusingSystemSecurityCryptographyX509Certificates
namespaceCascadeRestClientpublicclassOAuthResultpublicstringaccess_tokengetsetpublicstringexpires_ingetset
classProgramcallbackusedtovalidatetheself-gencertificateinanSSLconversationprivatestaticboolValidateRemoteCertificate(objectsenderX509CertificatecertX509ChainchainSslPolicyErrorspolicyErrors)returntrue
staticvoidMain(string[]args)if(argsLength==0||stringIsNullOrWhiteSpace(args[0]))ConsoleWriteLine(UsageCascadeRestClienthostname)returntryCodetoallowrunwithself-signedcertificatesvalidatecertbycallingafunctionServicePointManagerServerCertificateValidationCallback+=newRemoteCertificateValidationCallback(ValidateRemoteCertificate)
StartingtorunreststringrootUrl=https+args[0]stringOAUTH_CODE=ewoJIm5vbmNlIjogIjUyZGFhMzZjIiwKCSJhdWQiOiAiaHR0cHM6Ly9jc2MtcGVyZjE3LmxhYi5uYnR0ZWNoLmNvbS9hcGkvY29tbW9uLzEuMC9vYXV0aC90b2tlbiIsCgkiaXNzIjogImh0dHBzOi8vY3NjLXBlcmYxNy5sYWIubmJ0dGVjaC5jb20iLAoJInBybiI6ICJhZG1pbiIsCgkianRpIjogIjEiLAoJImV4cCI6ICIxMzU2NjMwNjA3IiwKCSJpYXQiOiAiMTM1NDAzODYwNyIKfQ==
stringrequestUrl=rootUrl+apicommon10oauthtoken
stringpostData=grant_type=access_codeampassertion=+OAUTH_CODEOAuthResultr
Loginusing(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpPostapplicationx-www-form-urlencodednullpostData))if(responseStatusCode=HttpStatusCodeOK)ConsoleWriteLine(LoginFailed)LogResponse(response)ConsoleRead()return
r=ReadResponseltOAuthResultgt(response)ConsoleWriteLine(PosttogettokenidissuccessfulnToken+raccess_token)ConsoleWriteLine(stringFormat(Thetokenwillexpirein0secondsrexpires_in))
PingtotestsessionauthenticationrequestUrl=rootUrl+apiprofiler10pingConsoleWriteLine(GET+requestUrl)
using(varresponse=MakeRequest(requestUrlWebRequestMethodsHttpGetapplicationjsonstringFormat(AuthorizationBearer0raccess_token)))if(responseStatusCode==HttpStatusCodeNoContent)ConsoleWriteLine(OAuth20authenticationissuccessful)else
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
elseConsoleWriteLine(OAuth20authenticationfailed)LogResponse(response)catch(Exceptione)ConsoleWriteLine(eMessage)ConsoleRead()
privatestaticvoidLogResponse(HttpWebResponseresponse)using(Streamstream=responseGetResponseStream())using(StreamReaderreader=newStreamReader(streamEncodingUTF8))StringresponseString=readerReadToEnd()ConsoleWriteLine(responseString)
privatestaticTReadResponseltTgt(HttpWebResponseresponse)whereTclass
DataContractJsonSerializerjsonSerializer=newDataContractJsonSerializer(typeof(T))objectobjResponse=jsonSerializerReadObject(responseGetResponseStream())returnobjResponseasT
ltsummarygtMakerequestltsummarygtltparamname=requestUrlgturlforrequestltparamgtltparamname=actiongtHttpVerbGetPostetcltparamgtltparamname=requestDatagtDatapostedltparamgtltreturnsgtltreturnsgtprivatestaticHttpWebResponseMakeRequest(stringrequestUrlstringactionstringcontenttypestringheaderstringrequestData=null)HttpWebRequestrequest=WebRequestCreate(requestUrl)asHttpWebRequesttryif(stringIsNullOrWhiteSpace(header))requestHeadersAdd(header)requestContentType=contenttyperequestAccept=applicationjsonrequestMethod=actionif(requestData==null)requestContentLength=0elseASCIIEncodingencoding=newASCIIEncoding()byte[]byte1=encodingGetBytes(requestData)requestContentLength=byte1Lengthusing(StreamnewStream=requestGetRequestStream())newStreamWrite(byte10byte1Length)
varresponse=requestGetResponse()asHttpWebResponsereturnresponsecatch(Exception)requestAbort()throw
Resources
Services List services
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
[ id string versions [ string ] ]
Example[ id common versions [ 10 ] id profiler versions [ 10 ] ]
login_banner string specify_purpose boolean supported_methods [ string ]
Example supported_methods [ BASIC COOKIE OAUTH_2_0 ] specify_purpose true login_banner A free-form text string that should be displayed to the user prior to logging in
Get information for supported API namespaces
GET httpsdeviceapicommon10services
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
services ltarrayofltobjectgtgt Listofnamespacesandversionssupportedbythesystem
services[service] ltobjectgt ObjectrepresentinganAPIservice
services[service]id ltstringgt IDoftheservicesuchasprofiler
services[service]versions ltarrayofltstringgtgt Listofversionsforagivenservice
services[service]versions[version] ltstringgt Versionoftheservice Optional
Auth_info Get authentication infoGet information for supported authentication methods
GET httpsdeviceapicommon10auth_info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
auth_info ltobjectgt Commonauthenticationinformation
auth_infologin_banner ltstringgt Loginbannerthataclientshoulddisplaybeforeuserslogin
auth_infospecify_purpose ltbooleangt Flagdescribingiftheloginpurposeshouldbespecified
auth_infosupported_methods ltarrayofltstringgtgt Listofsupportedauthenticationmethods
JSON
JSON
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
password string purpose string username string
Example username username password password purpose Purpose for loging in
session_id string session_key string
Example session_key SESSID session_id 164c38b379c7cff47fa8503a28743e5c8648d97dcbd0154f597673d9031a1c63
auth_infosupported_methods[method] ltstringgt Onemethodfromthelistofsupportedauthenticationmethods
OptionalValuesBASICCOOKIEOAUTH_2_0
Login LoginStart cookie based authentication session
POST httpsdeviceapicommon10loginusername=stringamppassword=stringamppurpose=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
username ltstringgt Usernamethatidentifiestheusertothesystem Optional
password ltstringgt Useraccountpassword Optional
purpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
Request BodyProvide a request body with the following structure
PropertyName Type Description Notes
login ltobjectgt Specificationforrequesttologin
loginpassword ltstringgt Password
loginpurpose ltstringgt Loginpurposedescribingwhytheuserlogsintothesystem Optional
loginusername ltstringgt Usernamethatidentifiestheusertothesystem
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
login ltobjectgt Responseforloginrequest
loginsession_id ltstringgt Valueofthesessioncookie
loginsession_key ltstringgt Nameofthesessioncookiethatshouldbestoredbytheclientandpresentedonsubsequentrequests
Oauth Get OAuth tokenGet a OAuth token based on OAuth code
POST httpsdeviceapicommon10oauthtokengrant_type=stringampassertion=stringampstate=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
grant_type ltstringgt ThetypeofauthorizationmethodusedtograntthistokenThevaluemustbeaccess_code
JSON
JSON
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
access_token string allowed_signature_types [ string ] expires_in number state string token_type string
Example access_token eyJhbGciOiJub25lIn0Kew0KICAiaXNzIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tIiwNCiAgImp0aSI6ICI3MjM1IiwNCiAgInBybiI6ICJjd2hpdGUiLA0KICAiYXVkIjogImh0dHBzOi8vcHJvZmlsZXIubGFiLm5idHRlY2guY29tL3Rva2VuIiwNCiAgImlhdCI6IDEzNDAwMjIwMTEsDQogICJleHAiOiAxMzQwMDI1NjExDQp9DQo=
token_type bearer allowed_signature_types [ none ] expires_in 3600 state a34rfFas
assertion ltstringgt TheaccesscodegeneratedbythesystemontheOAuthAccesspage
state ltstringgt Optionalclient-providedvaluethatwillbeechoedbackintheresponse Optional
Request BodyDo not provide a request body
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
token_response ltobjectgt TokenResponseobject
token_responseaccess_token ltstringgt Thegeneratedaccesstokenthatcanbeusedtoaccessprotectedresources
token_responseallowed_signature_types ltarrayofltstringgtgt Arrayofallowedsignaturemethods
token_responseallowed_signature_types[value] ltstringgt Allowedsignaturemethod Optional
token_responseexpires_in ltnumbergt Howlongthistokenisvalidfor
token_responsestate ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
token_responsetoken_type ltstringgt ThetokentypeOnlybeareriscurrentlysupported
Oauth Get Oauth codeimplicit tokenGet Oauth codeimplicit token for the current user
GET httpsdeviceapicommon10oauthauthorizeclient_id=stringampresponse_type=stringampdesc=stringampstate=stringampredirect_uri=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
client_id ltstringgt Clientidentifier Optional
response_type ltstringgt Thevaluemustbecodeforrequestinganaccesscodeandtokenforanaccesstoken
desc ltstringgt DescriptionoftheuseofthiscodeUsedinaudittraillogs Optional
state ltstringgt Includedifthestateparameterwaspassedinthetokenrequest Optional
redirect_uri ltstringgt URIthatwillbeusedforredirect Optional
Response BodyOn success the server does not provide any body in the responses
Ping PingSimple test of service availability
GET httpsdeviceapicommon10ping
AuthorizationThis request requires authorization
JSON
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
device_name string hw_version string mgmt_addresses [ string ] model string serial string sw_version string
Example sw_version 100 (release 20121106_2000) device_name cam-redfin2 mgmt_addresses [ 10389106 ] serial FB8RS00035E98 model 02260
Response BodyOn success the server does not provide any body in the responses
Logout LogoutEnd cookie based authentication session
POST httpsdeviceapicommon10logoutbanner_disagree=string
AuthorizationThis request requires authorization
ParametersPropertyName Type Description Notes
banner_disagree ltstringgt Usedwhenthesessionisbeingendedduetotheusernotagreeingtotheloginbannerconditions Optional
Request BodyDo not provide a request body
Response BodyOn success the server does not provide any body in the responses
Info Get infoGet appliance info
GET httpsdeviceapicommon10info
AuthorizationThis request requires authorization
Response BodyOn success the server returns a response body with the following structure
PropertyName Type Description Notes
info ltobjectgt Informationaboutthesystem
infodevice_name ltstringgt NameofthedevicethattheAPIisrunningon Optional
infohw_version ltstringgt Unsupported Optional
infomgmt_addresses ltarrayofltstringgtgt ListofIPaddresses
infomgmt_addresses[ip] ltstringgt IPaddress Optional
infomodel ltstringgt Modelofthedevice Optional
infoserial ltstringgt Serialnumberofthedevice Optional
infosw_version ltstringgt Versionofthesoftwarethatisrunningonthedevice Optional
Error CodesIn the event that an error occurs while processing a request the server will respond with appropriate HTTP status code and additionalinformation in the response body
JSON
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
error_id error identifier error_text error description error_info error specific data structure optional
The table below lists the possible errors and the associated HTTP status codes that may returned
ErrorID HTTPStatus Comments
INTERNAL_ERROR 500 Internalservererror
AUTH_REQUIRED 401 Therequestedresourcerequiresauthentication
AUTH_INVALID_CREDENTIALS 401 Invalidusernameandorpassword
AUTH_INVALID_SESSION 401 SessionIDisinvalid
AUTH_EXPIRED_PASSWORD 403 ThepasswordmustbechangedAccessonlytopasswordchangeresources
AUTH_DISABLED_ACCOUNT 403 Accountiseithertemporarilyorpermanentlydisabled
AUTH_FORBIDDEN 403 Userisnotauthorizedtoaccesstherequestedresource
AUTH_INVALID_TOKEN 401 OAuthaccesstokenisinvalid
AUTH_EXPIRED_TOKEN 401 OAuthaccesstokenisexpired
AUTH_INVALID_CODE 401 OAuthaccesscodeisinvalid
AUTH_EXPIRED_CODE 401 OAuthaccesscodeisexpired
RESOURCE_NOT_FOUND 404 Requestedresourcewasnotfound
HTTP_INVALID_METHOD 405 Requestedmethodisnotavailableforthisresource
HTTP_INVALID_HEADER 400 AnHTTPheaderwasmalformed
REQUEST_INVALID_INPUT 400 Malformedinputstructure
URI_INVALID_PARAMETER 400 URIparameterisnotsupportedormalformed
URI_MISSING_PARAMETER 400 Missingrequiredparameter
