Authorization & Authentication

Authorization / Authentication

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


Management of OAuth 2.0 Keys and of the Application Users is available in the above section. 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, 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 using (HttpClient httpClient = new HttpClient()) { httpClient.BaseAddress = new Uri(""); 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.

1 2 3 4 5 6 7 POST HTTP/1.1 Content-Type: application/x-www-form-urlencoded Authorization: Basic NDJmZjVkYWQzYzI3NGM5N2EzYTdjM2Q0NGI2N2JiNDI6Y2xpZW50MTIzNDU2 Host: 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 using (var client = new HttpClient()) { client.BaseAddress = new Uri(""); 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 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.