Authorization / Authentication

OAuth 2.0 Authentication settings are available at interworks.cloud BSS > Setup > Administration > System Options > API Credentials

Management of OAuth 2.0 Keys and of the Application Users is available in the above section.

interworks.cloud BSS API uses the OAuth 2.0 Resource Owner Password Flow in order to properly authorize and authenticate each request.

The Resource Owner Password Flow

The Resource Owner Password Flow is used to authenticate the consumer supposing that already has the application user’s credentials.

In this flow, the application user’s credentials are used by the application to request an access token by calling Request Token URL end point.

Getting the Access Token

Once OAuth 2.0 Authentication is enabled for an organiztion, the system issues 'Client Key' and 'Client Secret'.

By creating an application user, a set of username / password credentials should also be available.

These values could be used to a HTTP POST request to "/oauth/token" endpoint in order to receive an access_token value.

According to OAuth 2.0 specification, the 'Client Key' and 'Client Secret' value can be sent as request parameters. However, interworks.cloud Plarform accept these values only through basic authentication.

The following example demostrates a call for getting an access token using C# code.

C# Get Access Token Example

using (HttpClient httpClient = new HttpClient())
 {
          httpClient.BaseAddress = new Uri("http://my.interworkscloud.com/");
          var authorizationHeader = Convert.ToBase64String(Encoding.UTF8.GetBytes("23230e67-6c95-4f83-a176-d969b95ee601:HCHlt6XPXxOveEx4QjECVB4ChgKiLJF65U7qy/xe46k="));
          httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", authorizationHeader);
                    
          var form = new Dictionary<string, string> 
 		            { 
                             {"grant_type", "password"}, 
                             {"username", "testuser"}, 
                             {"password", "user123456!"}, 
                    }; 
 
          HttpResponseMessage response = httpClient.PostAsync("bsssmapi/oauth/token", new FormUrlEncodedContent(form)).Result;
		  string access_token = response.Content.ReadAsStringAsync().Result
 }

The request produced is provided below.

Request

POST http://my.interworkscloud.com/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic NDJmZjVkYWQzYzI3NGM5N2EzYTdjM2Q0NGI2N2JiNDI6Y2xpZW50MTIzNDU2
Host: my.interworkscloud.com
Content-Length: 56

grant_type=password&username=testuser&password=user123456

If all info is valid the response will contain the access token as provided below.

Response

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 550
Content-Type: application/json;charset=UTF-8
Expires: -1
Server: Microsoft-IIS/8.0
X-SourceFiles: =?UTF-8?B?RDpcRHJvcGJveFxBcHBzXFNhbXBsZXNcQXNwTmV0SWRlbnRpdHlTYW1wbGVzXFNpbXBsZU9BdXRoU2FtcGxlXFNpbXBsZU9BdXRoU2FtcGxlXG9hdXRoXHRva2Vu?=
X-Powered-By: ASP.NET
Date: Tue, 01 Apr 2014 13:56:32 GMT

{
    "access_token": "ydbP24rMOATt7TK3dBCjluD2F5LcLkoX8ud39X135x0a1LEvOgsPf0ekm4Lyu2a06Rv_Z105GRZT_NoclgTTf7Slt5_WNfe68zOUq22j6MqW4Fh__Abzjm6I8otDzxvCJpt5d73R-Um6GwTui3LDbcOk5bH2BZuQLTJsNLknbLPu_FdpgkYfBodUoyPiFhv5-gNBEsfp4gCZYfdKtlhaK0wtloZiIzH1_sNPhBt9FavSfThM5BeoWkz8PFxkv_cOsOhOIzK66nSx7B2XL7K9aLqPSJLxus2ud8GBZyteSeFi26L9oX9do7MyCL1nXa8D9DRWfcIXiQi1v19AwyhoupP3L-k89xOK6_NTSzYOVhSMG9Juz8VYHWGkJeYTmekmnVkCvQe7KMQ6PceeUFJnA88TkiHNhai0hV8j012OUxPpUN5zRPJOU81XywSkQ7oKE0UsX3hQamgFrXV9eA-TSwZd4Qr-P9w6a82OM66Te9E",
    "token_type": "bearer",
    "expires_in": 1799
}

Making a call

In order to call API methods, the derived access_token should be added in the 'Authorization' header (as defined in the OAuth 2.0 protocol).

An example call can be made using the following example.

C# API Call Example

using (var client = new HttpClient())
 {
           client.BaseAddress = new Uri("http://my.interworkscloud.com/");
           client.DefaultRequestHeaders.Accept.Clear();
           client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
		   client.DefaultRequestHeaders.Add("X-Api-Version", "latest");

           // Add the Authorization header with the AccessToken.
           client.DefaultRequestHeaders.Add("Authorization", "Bearer " + accessToken);


           // create the URL string.
           string url = string.Format("api/accounts/1");


           // make the request
           HttpResponseMessage response = await client.GetAsync(url);


           // parse the response and return the data.
           string jsonString = await response.Content.ReadAsStringAsync();
           object responseData = JsonConvert.DeserializeObject(jsonString);
 }

Sample Application for .NET Client

To get the code for the sample application, download Interworks.Cloud.BSS.API.Client.zip file.

The .zip file that you download contains a Visual Studio solution with a .NET Console Application that performs calls for receiving a access token and getting the synchronization options of an account.

Sample Application for JAVA Client

To get the code for the sample application, download the following file

The .zip file that you download contains a solution with a JAVA Application that performs calls for receiving a access token and getting the synchronization options of an account.

Authorization & Authentication