add docs for incident

imCodePartnerAB · Jun 17, 2016 · 68b10d0 · 68b10d0
1 parent f73c1d2
commit 68b10d0
Show file tree

Hide file tree

Showing 3 changed files with 410 additions and 20 deletions.
diff --git a/docs/api/authorization.rst b/docs/api/authorization.rst
@@ -1,8 +1,23 @@
 Authorization
 =============
 
-Step 1
-------
+Basic there are two steps working with authorization.
+
+First step divide into two different ways (with grant type authorization code or password) to retrieve
+access token object:
+
+    * In `Step 1 (first way)`_ you retrieve access token by two requests with authorization code:
+
+        * GET call (`Get authorization code`_)
+        * POST call (`Get access token with authorization code`_)
+
+    * In `Step 1 (second way)`_ you retrieve access token by one POST call with password
+
+Step 1 (first way)
+------------------
+
+Get authorization code
+~~~~~~~~~~~~~~~~~~~~~~
 
 In order to be authorized and to obtain the token you have to get authorization code first by sending GET request to
 
@@ -11,12 +26,15 @@ In order to be authorized and to obtain the token you have to get authorization
 where
 
 {yourClientId} is ID of your client (provided by iVIS administrators)
+
 {redirectUrl} is the URL that will receive authorization code after successful authorization
+
 {scope} is the list of the required permissions (currently you can use 'read+write')
 
 Code example **Java** using org.apache.http package
 
-.. code-block:: properties
+.. code-block:: java
+   :linenos:
 
    String authorizeURI = "http://ivis.dev.imcode.com/oauth/authorize";
    String redirectURI = "{redirectUrl}";
@@ -34,7 +52,8 @@ Code example **Java** using org.apache.http package
 
 Code example **JS** using JQuery
 
-.. code-block:: properties
+.. code-block:: javascript
+   :linenos:
 
    var authorizeURI = "http://ivis.dev.imcode.com/oauth/authorize";
    var redirectURI = "{redirectUrl}";
@@ -51,8 +70,8 @@ Code example **JS** using JQuery
 
    location.href = authorizeURI + '?' + $.param(data);
 
-Step 2
-------
+Get access token with authorization code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When you have the authorization code (it is sent by GET request to your {redirectUrl}) you can try to get token by
 sending POST request to
@@ -62,9 +81,13 @@ sending POST request to
 with parameters
 
 code (= '{code}')
+
 client_id (= '{yourClientId}') - the same as in step 1
+
 client_secret (= '{yourClientSecret}')
+
 redirect_uri (= '{redirectUrl}') - the same as in step 1
+
 grant_type = (= 'authorization_code')
 
 This necessary if you want receive token on server side (see Java example).
@@ -77,15 +100,17 @@ See JS example.
 As response to the redirect_uri you will receive json object with next properties:
 
 access_token (token for access to API)
+
 refresh_token (when token is expired, you can exchange refresh_token to new access_token, see step 3)
-expires_in (property is a number of seconds after which the access token expires, and is no longer valid)
 
-access_token object has another properties, but trey aren't necessary for accessing to API.
+expires_in (property is a number of seconds after which the access token expires, and is no longer valid)
 
+access_token object has also another properties, but they aren't necessary for accessing to API.
 
 Code example **Java** using org.apache.http package
 
-.. code-block:: properties
+.. code-block:: java
+   :linenos:
 
    String tokenURI = "http://ivis.dev.imcode.com/oauth/token";
    String redirectURI = "{redirectUrl}";
@@ -102,13 +127,14 @@ Code example **Java** using org.apache.http package
    HttpPost post = new HttpPost(tokenURI);
    post.setEntity(new UrlEncodedFormEntity(pairsPost));
    HttpClient client = new DefaultHttpClient();
-   HttpResponse responses = client.execute(post);
+   HttpResponse response = client.execute(post);
 
-   String token = EntityUtils.toString(responses.getEntity()); //there is a json object response
+   String token = EntityUtils.toString(response.getEntity()); //there is a json object response
 
 Code example **JS** using JQuery
 
-.. code-block:: properties
+.. code-block:: javascript
+   :linenos:
 
    var tokenURI = "http://ivis.dev.imcode.com/oauth/token";
    var redirectURI = "{redirectUrl}";
@@ -135,49 +161,120 @@ Code example **JS** using JQuery
         }
     });
 
-Step 3
+Step 1 (second way)
+-------------------
+
+You can obtain access token by providing your login and password in one POST request to
+
+/oauth/token
+
+with parameters
+
+username (= '{yourUsername}')
+
+password (= '{yourPassword}')
+
+client_id (= '{yourClientId}')
+
+client_secret (= '{yourClientSecret}')
+
+grant_type (= 'password')
+
+As response to the redirect_uri you will receive json object with next properties:
+
+access_token (token for access to API)
+
+refresh_token (when token is expired, you can exchange refresh_token to new access_token, see step 3)
+
+expires_in (property is a number of seconds after which the access token expires, and is no longer valid)
+
+access_token object has also another properties, but they aren't necessary for accessing to API.
+
+Code example **Java** using org.apache.http package
+
+.. code-block:: java
+   :linenos:
+
+   String tokenURI = "http://ivis.dev.imcode.com/oauth/token";
+   String clientId = "{yourClientId}";
+   String clientSecret = "{yourClientSecret}";
+   String username = "{yourUsername}";
+   String password = "{yourPassword}";
+
+   List<NameValuePair> pairsPost = new LinkedList<NameValuePair>();
+   pairsPost.add(new BasicNameValuePair("username", username));
+   pairsPost.add(new BasicNameValuePair("password", password));
+   pairsPost.add(new BasicNameValuePair("client_id", clientId));
+   pairsPost.add(new BasicNameValuePair("client_secret", clientSecret));
+   pairsPost.add(new BasicNameValuePair("grant_type", "password"));
+
+   HttpPost post = new HttpPost(tokenURI);
+   post.setEntity(new UrlEncodedFormEntity(pairsPost));
+   HttpClient client = new DefaultHttpClient();
+   HttpResponse response = client.execute(post);
+
+   String token = EntityUtils.toString(response.getEntity()); //there is a json object response
+
+Step 2
 ------
 
-When your token is expired you can refresh (update) it without repeating authorization by sending POST request to
+When your token is expired  you can refresh (update) it without repeating authorization by sending POST request to
 
 /oauth/token
 
 with parameters
 
 refresh_token (='{yourRefreshToken}') - is the refresh token from the step 2
+
 grant_type (= 'refresh_token')
 
+client_id (= 'yourClientId')
+
+client_secret (= 'yourClientSecret')
+
 Code example **Java** using org.apache.http package
 
-.. code-block:: properties
+.. code-block:: java
+   :linenos:
 
    String tokenURI = "http://ivis.dev.imcode.com/oauth/token";
    String refreshToken = "{yourRefreshToken}";
+   String client_id = "{yourClientId}";
+   String client_secret = "{yourClientSecret}";
+   String refreshToken = "{yourRefreshToken}";
 
    List<NameValuePair> pairsPost = new LinkedList<NameValuePair>();
    pairsPost.add(new BasicNameValuePair("refresh_token", refreshToken));
    pairsPost.add(new BasicNameValuePair("grant_type", "refresh_token"));
+   pairsPost.add(new BasicNameValuePair("client_id", client_id));
+   pairsPost.add(new BasicNameValuePair("grant_type", "refresh_token"));
 
    HttpPost post = new HttpPost(tokenURI);
    post.setEntity(new UrlEncodedFormEntity(pairsPost));
 
    HttpClient client = new DefaultHttpClient();
-   HttpResponse responses = client.execute(post);
+   HttpResponse response = client.execute(post);
 
-   String token = EntityUtils.toString(responses.getEntity()); //there is a json object response
+   String token = EntityUtils.toString(response.getEntity()); //there is a json object response
 
 Code example **JS** using JQuery
 
-.. code-block:: properties
+.. code-block:: javascript
+   :linenos:
 
    var tokenURI = "http://ivis.dev.imcode.com/oauth/token";
    var refreshToken = "{yourRefreshToken}";
+   var client_id = "{yourClientId}";
+   var client_secret = "{yourClientSecret}";
 
    $.post({
        url : tokenURI,
        data : {
            'refresh_token' : refreshToken,
-           'grant_type' : 'refresh_token'
+           'grant_type' : 'refresh_token',
+           'client_id' : client_id,
+           'client_secret' : client_secret,
+           'grant_type' : 'refresh_token',
        },
        success : function (token) {
                      alert(token['access_token']); //use received token