This article provides technical details of the JavaScript authentication process. In most circumstances, JavaScript API access should be performed via the JavaScript SDK, which takes care of authentication and uses API best practices.

Authenticating from JavaScript is different to standard API authentication, since the standard authentication mechanism would expose the AppSecret in a purely client-based application, which would be a serious security breach.

First of all, any domain that needs to access the API using JavaScript must be registered in dialogportal™. Contact the Account Manager in charge of your solution at Fluid for assistance with this.

For a JavaScript application to be allowed to make calls to the API, it must send an API authentication token as a URL argument or HTTP header with every request. This token must be created using the dialogportal™ JavaScript authentication SDK.

Step 1 - Include the SDK

Include the dialogportal™ JavaScript authentication SDK. Adding the following line to the HEAD section of your HTML page does this:

<script>document.writeln('<script src="https://api.dialogportal.com/v1/authentication/auth.js?s=' + Math.random().toString(36).substr(2,16) + '"><\/script>');</script>

Step 2 - Authenticate

Authentication is done with the JavaScript function rs.api.auth.getTokenAsync(). It takes three arguments: AppID, event handler in case of success and finally the event handler in case of error. The following sample shows how to do it (Replace APP_KEY):

function authenticate() {
	rs.api.auth.getTokenAsync(APP_KEY, authSuccess, error);
}

function authSuccess() {
	alert("Success! " + rs.api.auth.token);
}

function error(status, textStatus, errorThrown) {
	alert(status + ", " + textStatus + ", " + errorThrown);
}

Step 3 - Use the authentication token

After successfully authenticated, you should add the authentication token rs.api.auth.token as an argument to all API requests. The following sample shows how to authenticate a user/entity and then output the details returned from the API using jQuery:

function authenticateUser() {
	$.ajax({
		type: "POST",
		contentType: "application/json; charset=UTF-‐8",
		dataType: "json",
		data: "{ 'authType': 'native', 'loginID': 'you@know.Me', 'password': 'password' }",
		url: "https://api.dialogportal.com/v1/user/authenticate?apiauthtoken=" + rs.api.auth.token,
		processData: false,
		success: authenticateUserSuccess, 
		error: error
	});
}
 
function authenticateUserSuccess(data) {
	var s = "";
	for (var i in data)
		s += i + ": " + data[i] + "\n";
	alert(s);
}

Please note, that the API authentication token is only valid for one hour since the last request. In case it expires, the request will fail with HTTP error 401 (Bad signature). This error can be identified in the error handler using the status object. Simply request a new authentication token as described in step 2, but bear in mind that the included auth.js (step 1) is only valid for 24 hours. After 24 hours, you will have to request a new version of auth.js.

The SDK uses AJAX to interact with the API. It uses native JavaScript/ECMAScript functionality (XMLHttpRequest), but when jQuery is present on the page then jQuery will be used instead.

Browser not supported