Posted Nov 15 by AppWorks Developer.
Updated Nov 16.

This guide demonstrates how to access the provided otagtoken, setting the proper header to send to the server, and how to handle the case where the user is not authenticated.

7546 views. 0 comments.

This guide uses the Sample Service created in the Adding Authenticated Endpoints guide. You should follow that guide before reading this one, or download the service from it.

Authentication Users

AppWorks automatically provides deployed applications with an otagtoken for the logged in user. This otagtoken must then be passed to the server in order to authenticate the current user. The recommended practice for this is to provide the otagtoken to the server via a custom header.

In this guide we'll go through how to access the provided otagtoken, setting the proper header to send to the server, and how to handle the case where the user is not authenticated.

Getting the Token

AppWorks automatically provides you with an otagtoken for the currently logged in user. However, there are a couple of ways to access this token depending on the way the app is viewed. This is due to some browser limitations and will be abstracted to an included JavaScript library in the future.

For now, we'll create our own function to retrieve the otagtoken from AppWorks. We'll also include a getCookie() function to help retrieve the token in the event that we're using WebAccess.

    // Get the otagtoken for the current user
    function getToken() {
        var token;

        // Check if the token is inserted into a global object
        // This is the case for AppWorks apps
        if (window.otag && otag.auth) {
            token = otag.auth.otagtoken;
        } else {
            // Get the token from a cookie
            // This is the case for webaccess
            token = getCookie( 'otagtoken' );

            // Set the token into a global object for future use
            setToken( token );

        return token;

    // Set the otagtoken for the current user
    function setToken(token) {
        window.otag = otag || {};
        otag.auth = otag.auth || {};
        otag.auth.otagtoken = token;

    // Get a cookie value by name
    // Source:
    function getCookie(name) {
        // Split by name=value;
        var parts = document.cookie.split( name + '=' );

        // If the cookie exists, there is now a 'name=' vaule and
        // a 'value; ...' value
        if ( parts.length === 2 ) {
            // Pop off the 'value; ...', split it into 'value' and
            // '; ...' parts, and then return the 'value' piece
            return parts.pop().split( ';' ).shift();

Adding this function into the app.js will allow us to retrieve this token and use it for the app.

Sending the Token

Now that we can retrieve the token from the application, we need to modify the Profiles.prototype.index() method to add it to a custom header. To accomplish this, we'll create a generic ajax function.

    // Load an AJAX request and set the otagtoken header
    Profiles.prototype.ajax = function (options) {
        var token = getToken();

        // Set the otagtoken on the correct header
        options.beforeSend = function (req) {
            req.setRequestHeader( 'otagtoken', token );

        return $.ajax( options ).
            always(function (data) {
                // If the response contains a new otagtoken, update it
                if ( data && data.otagtoken ) {
                    setToken( data.otagtoken );

This will automatically get the token and send it each time the Profiles.prototype.ajax(data) method is called. Another advantage of this function is that it will update the otagtoken from any response that contains an otagtoken value.

Updating the Profiles App

Now that we can send the otagtoken to the server we need to update the existing Profiles.prototype.index() call to use this new function. This is a simple change - just change the $.ajax call into this.ajax.

    // Load a list of profiles from the server and display them
    Profiles.prototype.index = function () {
        var _this = this;

        // Return promise to allow chaining
        return this.ajax({
            url: this.baseUrl + '/SampleService/v1/profiles'
            done(function (data) {
                // Automatically build and show the list of profiles
                $( _this.sel ).html( _this.buildItem( data ) );
            fail(function () {
                _this.displayError( 'There was a problem loading profiles.' );

Since the data returned has also been changed, we must change the _this.buildList( data ) call into a _this.buildItem( data ) call. This will now display the single profile returned. Similarly, the Profiles.prototype.buildItem(item) method must be changed to reflect the new data.

    // Build a single profile structure
    Profiles.prototype.buildItem = function (item) {
        return (
            '<div class="profile-item">' +
                '<h3 class="profile-header">' + item.username + '</h3>' +
                '<strong>External:</strong> ' + item.external + '<br>' +
                '<strong>Admin:</strong> ' + (item.admin ? 'Yes' : 'No') +

Notice that there isn't as much relevant information returned from this call. We'll improve on that in a future AppWorks guide.

Deploying the New App

You should now be able to save the app, create the App bundle, and upload the new file to the AppWorks Gateway.

Just like an AppWorks Service, the version number of the ZIP file needs to change in order for AppWorks to recognize an updated application. Update the file name to to register the changes.

Now when you open the application it should update to the latest version. You should then see the new information returned from the server (Username, External, and Admin).

Source code

Download the Profiles app bundle created in this guide.

Profiles app bundle (103kB)

Table of Contents

Your comment

To leave a comment, please sign in.