How to Use Formilla JavaScript & REST APIs Securely

In this post, you’ll learn how to add a security layer to protect your users’ data if you’re currently using, or you’re planning to use, the Formilla JavaScript API. We’ll also show you how to enable the Formilla REST API — which is disabled by default — to generate your secure token, and what you need to do to successfully use the REST API.

Before proceeding further, be sure to check out both API posts if you haven’t already.

Note: if you’re using Formilla with a Wix website, integration of your data is not supported and the security settings referenced below will not be displayed.

How do I enable secure mode with the JavaScript API?

To begin, we highly recommend enabling secure mode when integrating your users’ data with the JavaScript API. This will maintain the integrity of your data, and ensure that any JavaScript calls to Formilla are actually coming from you, and not being impersonated by someone else.

  1. First, simply login to your Formilla account as the Account Owner and then click Settings from the left menu.
  2. On the next page, choose Security from the sub-menu as shown.
    Security section
    Note: be sure you’re logged in as the Account Owner, otherwise you won’t have access to the Security page.
  3. Under the Formilla JavaScript API header, toggle the Secure Mode Enabled option to Yes and click OK on the confirmation dialog that appears.
  4. You have now successfully enabled secure mode and a Secure Key should be displayed.
    Note: obviously, do not share your Secure Key publicly with anyone and be sure to keep it safe!
  5. Next, you’ll need to generate a SHA256 HMAC when your user is logged-in and pass it into the Formilla script when initializing your user. To accomplish this, you’ll need:
    • the Secure Key;
    • the User ID or Email Address of the logged-in user (more on this below)
      Security key

     

    Don’t worry, all major platforms and languages will have a method to help you generate the HMAC. Below, I’ve listed a few examples that you may find useful.

    You’ll notice the User ID is being used to generate the HMAC, however if you’re not using a User ID (e.g. a customer ID, account ID, some other unique identifier, etc.) to uniquely identify each logged-in user, then email address is required as the identifier and should be used when generating the HMAC.

    PHP

    $data = $user->id;
    
    $contact_hmac = hash_hmac('sha256', $data, 'CSCD537A-4A00-4007-AB78-C3F3B17A730A');

     

    C#

    var keyBytes = Encoding.UTF8.GetBytes("CSCD537A-4A00-4007-AB78-C3F3B17A730A");
    var valueBytes = Encoding.UTF8.GetBytes(User.Id.ToString()); 
    var hmac = new HMACSHA256(keyBytes);
    var hmacBytes = hmac.ComputeHash(valueBytes);
    
    var contactHmac = BitConverter.ToString(hmacBytes).Replace("-", string.Empty);
    

     

    Java

    import javax.crypto.Mac;
    import javax.crypto.spec.SecretKeySpec;
    import org.apache.commons.codec.binary.Base64;
    ...
    try {
        String secret = "CSCD537A-4A00-4007-AB78-C3F3B17A730A";
        String value = User.Id.toString();
    
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
        sha256_HMAC.init(secret_key);
    
        String contact_hmac = Base64.encodeBase64String(
            sha256_HMAC.doFinal(value.getBytes()));
    }
    catch (Exception e) {
        // Log error
    }

    Note: please keep in mind that this Java example needs a reference to the Apache Commons Codec package to work successfully.

  6. Pass the generated HMAC to Formilla into the script code on your website in the Formilla.contactHmac variable as follows:
    (function () {
    	var head = document.getElementsByTagName("head").item(0);
    	var script = document.createElement("script");
    	
    	var src = (document.location.protocol == 'https:' 
    		? 'https://www.formilla.com/scripts/feedback.js' 
    		: 'http://www.formilla.com/scripts/feedback.js');
    	
    	script.setAttribute("type", "text/javascript"); 
    	script.setAttribute("src", src); script.setAttribute("async", true);        
    
    	var complete = false;
    	
    	script.onload = script.onreadystatechange = function () {
    		if (!complete && (!this.readyState 
    			|| this.readyState == 'loaded' 
    			|| this.readyState == 'complete')) {
    		    complete = true;
    		    Formilla.guid = 'cscd537a-4a00-4007-ab78-c3f3b17a730a';
    			
    		    // Contact attributes
    		    Formilla.contactAttributes = {
    			UserId: "100",                         // Contact Id
    			Email: "[email protected]",       // Contact email address
    			FirstName: "Mike",                     // Contact first name
    			LastName: "Thompson"                   // Contact last name
    		    };
    
    		    Formilla.contactHmac = "SET_HMAC_VALUE_HERE"; // HMAC
    			
    		    Formilla.loadWidgets();                
    		}
    	};
    
    	head.appendChild(script);
    })();

    Note: remember, when integrating your users’ data into Formilla, you need to have the script code installed manually on your site and should not be using our plugins.

    Please be aware that if the generated HMAC is invalid, the user data won’t be integrated into your Formilla account and will cause the script to fail when loading.

How do I enable the Formilla REST API?

As mentioned previously, the REST API must be first enabled if you plan to use it to integrate your users’ data inside of Formilla.

  1. Login to your Formilla account as the Account Owner and then click Settings from the left menu.
  2. On the next page, choose Security from the sub-menu on the left side.
  3. Simply toggle the REST API Enabled option to Yes under the Formilla REST API heading.
  4. You should now see a Secure Token generated. Each API call you make needs to include the Secure Token in the request header in the formilla_auth_token parameter. Check out the following example where we update a contact:

    Request

    HTTP Method
    POST
    
    Request URL
    https://api.formilla.com/api/contacts
    
    Header
    Content-Type: application/json
    formilla_auth_token: eyJDdXN0b21lclNpdGVHdWlkIjoiY3NjZDUzN2EtNGEwMC00MDA3LWFiNzgtYzNmM2IxN2E3MzBhIiwiUHVibGljQXBpQXV0aFRva2VuIjoiQThDOEE4RkQtRTZFNy00QUQwLUI2MzYtMzVDMjM5QkIwQTY4In0=
    
    Body
    {
      "UserId": "100",
      "Email": "[email protected]",
      "FirstName": "Mike",
      "LastName": "Thompson"
    }

     

    Response

    Formilla REST API returns standard HTTP response codes.
    (200 OK, 403 Forbidden, 500 Server Error, etc.)

 You can learn more about our REST API at this link.

Creating a new secure key or token

In the event you need to generate a new Secure Key or Token, you can do so by clicking the Create New Key or Create New Token buttons on the Security page, and then click OK on the confirmation dialog that appears. Of course, changing your key/token will require you to update your code to use the new value(s).
Create new security key

 

As always, please contact us at [email protected] if you have any questions 🙂

Join the Formilla blog!

We offer actionable advice about live chat, chat bots, marketing automation, customer service, and sales. Sign up and we'll send you the best of the blog, from articles to infographics, every two weeks.

100% privacy. Unsubscribe any time.