To start your custom application development, perform the steps below.

Size: px

Start display at page:

Download "To start your custom application development, perform the steps below."

Candace Bishop
5 years ago
Views:

3. Create yur custm applicatin t btain the identifying infrmatin: the Client ID and Secret Key. 1.

1 Get Started T start yur custm applicatin develpment, perfrm the steps belw. 1. Sign up fr the kitewrks develper package. Clud Develper Package Develper Package 2. Sign in t kitewrks. Once yu have yur instance f kitewrks up and running, sign in t the kitewrks admin interface with yur user credentials. The admin interface can be accessed frm the hstname f yur kitewrks server /admin. 3. Create yur custm applicatin t btain the identifying infrmatin: the Client ID and Secret Key. 1. On the kitewrks Administratr s Dashbard, g t Applicatin > Client Management > Custm Applicatins and add yur custm applicatin. Specify the name fr yur app. Under Flws select Authrizatin Cde Specify the Redirect URI using this frmat Chse yur Access Tken Lifetime 2. Add yur Custm Applicatin. Yu will be given the Client Applicatin ID and Client Secret Key fr yur applicatin. IMPORTANT: Yu must cpy this infrmatin and keep it in a secure lcatin. The Client Secret Key is required fr authenticating yur app. If yu lse this infrmatin, yu will have t start ver and re-register yur app. 4. Cnfigure yur Custm Applicatin. The kitewrks APIs are used by the custm applicatins t access user resurces n a kitewrks server. The kitewrks APIs are used by the custm applicatins t access user resurces n a kitewrks server. API Usage The APIs fllw the REST architectural style and use the scheme f addressing a resurce and invking a methd n that resurce. The API URI All APIs can be called using the fllwing URI scheme: API Output The API result is returned in JSON frmat. kitewrks OAuth 2.0 Flw The kitewrks APIs allws any new client applicatin (client fr shrt) t be develped fr the kitewrks slutin. The APIs can be used by the client t gain access t resurces belnging t a user n the kitewrks server. The APIs can nly be used by a client that is registered n the kitewrks server.

2 A client must prvide an access tken t access resurces belnging t a user n the kitewrks server. The kitewrks server prvides access tken prvisining flws based n the OAuth 2.0 ( The majrity f clients will cnsume the s-called Authrizatin Cde Flw t btain an access tken. This flw is develped based n the authrizatin cde grant type f the OAuth 2.0 specificatin. This dcument prvides a step-by-step guide fr applicatin develpers t build a client fr cnsuming the Authrizatin Cde Flw t btain an access tken and use the access tken t access users resurces n a kitewrks server. Example cdes fr Andrid based clients are als prvided. Obtaining Access Tken Requirements Fr btaining an access tken using the kitewrks Authrizatin Cde Flw, yu need the client registratin infrmatin recrded in the previus steps: client_id This is a unique system generated id f yur client. client_secret This secret serves as a passwrd fr yur client t authenticate itself t the kitewrks server. redirect_uri This is the URI n which yur client must listen fr the authrizatin result. Fr mbile clients r fr clients that cannt be redirected t anther service, the landing page can be used. scpe This is the set f API services that yur client wants t access. Cnsult with yur administratr regarding which scpes are available fr yur client. Sequence Overview 1. The sequence f the Authrizatin Cde Flw is as fllws: 2. The client initiates the flw by redirecting the user-agent (brwser r web view cmpnent) t the apprpriate authrizatin page n the server. The client includes its id and a redirect URI t which the server will send the user back nce access is granted r denied. 3. The server authenticates the user using a lgin page similar t web client lgin page and establishes whether the user grants r denies the client's access request. 4. If the user grants access, the server redirects the user-agent t the redirectin URI prvided earlier. The URI als includes an authrizatin cde that can be used t request an access tken fr that user. 5. The client requests an access tken frm the server by authenticating itself (using its id and secret) and including the authrizatin cde received in the previus step. 6. The server validates the client credentials and the authrizatin cde and respnds with the access tken. The client uses the access tken t invke APIs fr accessing user s resurces. Step-by-step Usage The request-respnse f this flw fllws the specificatin f OAuth 2.0 prtcl ( All requests fr authrizatin and fr calling service must be dne thrugh HTTPS. The URI end-pints f this flw are as fllws: Authrizatin end-pint: Tken end-pint: All request parameters, unless therwise specified, must be passed thrugh HTTP POST parameters. The respnse bdy will be in JSON frmat. The fllwing infrmatin describes this in mre detail.

3 Step 1 Authrizatin Request The first step is t call the Authrizatin end-pint with the request parameters passed via HTTP GET. Depending n the case, the user may be prmpted with a dialg t authenticate and then t authrize the request fr access permissin by the client applicatin. The fllwing parameters must be passed in the request t the Authrize URI (this fllws the OAuth 2 specificatin). client_id is the identifier f the client-applicatin as registered in the server. Fr example playgrund. redirect_uri is the URI t which the result f the authrizatin will be passed. This redirect URI must start with the URI specified at the time f the creatin/registratin f the client applicatin. Fr example, if the client applicatin had registered with the redirect URI f then the client applicatin may prvide as redirect_uri parameter in this request. Please nte that this parameter must be prperly URL-encded. respnse_type the value f this parameter must be set t cde. scpe is the scpe f the API services that the client wants t access. This is a space-separated string cnsisting f the name f the methd and API services that the applicatin requires. Fr example: GET/users/* */files/*. The requested scpe must be a sub-set f the client applicatin's registered scpe in the server. If a blank scpe is prvided, the registered scpe will be assumed. m (ptinal parameter) set t 1 t display mbile friendly authrizatin page. state (ptinal parameter) is an ptinal parameter that the client applicatin may pass in rder t maintain the state f its prcess. The server will pass back this parameter as-is in the respnse. Example: (Nte that line break is used nly fr clarity) GET client_id=abc&respnse_type=cde&scpe=&redirect_uri= https%3a%2f%2fkitewrks_server%2fauth_callback.php HTTP/1.1 Successful Respnse After the server finishes the authrizatin and authenticatin prcedure with the user, the server will redirect the user (via HTTP 302) t the redirect_uri prvided in the Authrize call. Tw parameters will be passed thrugh this redirectin URI: cde and state. The cde parameter is the authrizatin cde that can be used t btain the access tken in the secnd step. Example HTTP/ Fund Lcatin: Errr Respnse If an errr ccurs (such as invalid cnsumer id, r invalid redirect URI), an errr message will be displayed immediately within the user s brwser. Fr ther errrs (such as invalid scpe r denied access by the user) the server will redirect the user (via HTTP302) t the redirect_uri. The parameters are given belw. errr is the errr cde. The fllwing are the pssible values f the errr cde: access_denied: The user denied the permissin request. invalid_scpe: The requested scpe is invalid. invalid_request: The request is missing a required parameter, includes an unsupprted parameter r parameter value, r is therwise malfrmed.

4 unauthrized_client: The client-applicatin is nt authrized t use this flw. state is set t the exact value received in the request. Example: HTTP/ Fund Lcatin: kitewrks_server/auth_callback.php?errr=access_denied Step 2 - Access Tken Request The authrizatin cde btained in the first step can be exchanged fr the final access tken by making a request t the access tken end-pint. The fllwing parameters must be passed t the tken end-pint as POST parameters: client_id is the ID f the client as registered in the server. E.g. playgrund. client_secret is the client s secret phrase as registered in the server. grant_type its value must be set t authrizatin_cde. redirect_uri is exactly the same redirect URI as used in the first step. cde is the authrizatin cde btained in the first step. install_tag_id (ptinal parameter) is a string t uniquely identify the device frm which the API call has initiated. install_name (ptinal parameter) is the friendly name f the device frm which the API call has initiated. Example: (Nte that line breaks n the message cntent are used nly fr clarity) POST /auth/tken HTTP/1.1 Hst: kitewrks_server Cntent-type: applicatin/x-www-frm-urlencded client_id=abc&client_secret=thesecret&grant_type=authrizatin_cde&cde=c88bc36f751549adf60658c2c607a03b5 2e417bc& redirect_uri= https%3a%2f%2fkitewrks_server%2fauth_callback.php &install_tag_id=device_123&install_name=user_ipad Successful Respnse If the credentials f the client and the authrizatin cde are valid and there is n ther errr, the server will return a HTTP respnse 200 OK. The bdy f the respnse is in JSON frmat with the fllwing infrmatin: access_tken is the tken that can be used t request an API service. expires_in is the number in secnds after which the access tken wuld expire. tken_type is set t bearer scpe is the scpe fr which this tken is valid, nrmally it will be the same as the requested scpe. refresh_tken is the refresh tken that can be used t get a new access tken withut ging thrugh step 1 f Authrizatin. This refresh tken will be prvided nly if the client is allwed t use refresh tkens as specified during client registratin. Example: HTTP/ OK Cache-Cntrl: n-stre

5 Cntent-Type: applicatin/jsn {"access_tken":"d932e1d32d d47fa97bfa60eeba1a5","expires_in":"360000","tken_type":"bearer", "scpe":"get\/users\/* *\/files\/*","refresh_tken":"d7ce54d721e8das60943f3fc7cb159e4b11d0ee5"} This access tken can then be used t access user's resurces thrugh API services. Errr Respnse If the credentials f the client r the authrizatin cde is invalid r there is sme ther errr, the server will respnd with HTTP 400 Bad Request. The bdy f the respnse will cntain the fllwing errr infrmatin in JSON frmat: errr is the errr cde. The fllwing are the pssible values : invalid_client Client authenticatin failed. The client ID and/r secret key prvided is invalid. invalid_grant The authrizatin cde r redirect URI prvided is invalid. invalid_scpe The requested scpe is invalid r exceeds the previusly granted scpe. invalid_request The request is missing a required parameter, includes an unsupprted parameter r parameter value, r is therwise malfrmed. unauthrized_client The client is nt authrized t use this flw. Execute API Calls Nw that we have the access tken, it is time t get started with using the kitewrks API in yur mbile applicatin. Befre we begin, select the value f the access tken returned frm the respnse executed in the previus step. Frm the example respnse the value is: d932e1d32d d47fa97bfa60eeba1a5 Paste the tken in the input field f the Develper Dcumentatin page as shwn belw. Let's begin with perfrming a basic API call. In the bdy f the webpage, there is a list f entities, each f which crrespnd t a different part f kitewrks and is represented with a JSON paylad. When an entity name is clicked, the interface will expand t shw all f the endpints assciated with that entity. An endpint is a web request that perfrms a task related t the entity it falls under. As an example, navigate t the users entity.

6 Here, yu can see the list f endpints assciated with the users entity. Fr clarity purpses, they are clr cded based n what methd is being used. T the right f each list item, there is a brief descriptin f what the entity des. When an item in this list is clicked, the interface will expand again t shw infrmatin relevant t the selected endpint. Click n the endpint GET /users/me.

7 G ver the details fr this endpint. In summary, it returns a JSON representatin f the entity that is ppulated with infrmatin that the access tken represents. This infrmatin is tied t the current user. Once yu've gne ver the infrmatin fr the endpint, click the Try it ut! buttn.

8 In the Respnse Bdy sectin, there will be a JSON bject f the users class, and it will cntain the current user's infrmatin.

LiveEngage and Microsoft Dynamics Integration Guide Document Version: 1.0 September 2017

LiveEngage and Microsoft Dynamics Integration Guide Document Version: 1.0 September 2017 LiveEngage and Micrsft Dynamics Integratin Guide Dcument Versin: 1.0 September 2017 Cntents Intrductin... 3 Step 1: Sign Up... 3 CRM Widget Signing Up... 3 Step 2: Cnfiguring the CRM Widget... 4 Accessing