Authorization & Authentication – interworks.cloud Portal

Table of Contents

1 Authorization / Authentication
- - 1.0.1 The Resource Owner Password Flow
  - 1.0.2 Getting the Access Token
2 Making a call
- - - 2.0.0.1 C# API Call Example
3 Sample Application for .NET Client
4 Sample Application for JAVA Client

Authorization / Authentication

To make calls to the interworks.cloud BSS and Billing API you must be authorized and authenticated.

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 this section.

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

The Resource Owner Password Flow

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

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

Getting the Access Token

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

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

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

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

The following example demonstrates a call which gets 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 responseBody = response.Content.ReadAsStringAsync().Result
 }

The request produced is shown 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 shown 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

To call API methods, the derived access_token must be included in the Authorization header (as defined in the OAuth 2.0 protocol).

A 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, please download the following file:

interworks.cloud.BSS.API.client.zip

The .zip file contains a Visual Studio solution with a .NET Console Application that performs calls to receive an access token and get the synchronization options of an account.

Sample Application for JAVA Client

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

bss.api_.client.JAVA_.zip

The .zip file contains a solution with a JAVA Application that performs calls to receive an access token and get the synchronization options of an account.