App authentication in native apps

After your app authorized a merchant, it will need an access token for the Ecwid REST API to read and modify Ecwid store orders, products and other information.

The process of getting an access token is different for each user authentication type. Both authentication types are described below, so please check them out for more info on getting access tokens.

Default User Auth

Example of the iframe URL call in client-side apps: https://www.example.com/my-app-iframe-page#53035362c226163636573735f746f6b656e223a22776d6

//
//  Get store details
//
    var storeData = EcwidApp.getPayload();
    var storeId = storeData.store_id;
    var accessToken = storeData.access_token;
    var language = storeData.lang;
    var viewMode = storeData.view_mode;
    
    if (storeData.public_token !== undefined){
      var publicToken = storeData.public_token;
    }
    
    if (storeData.app_state !== undefined){
      var appState = storeData.app_state;
    }

//
//  Get store specific data
//

    var backgroundColor;
    EcwidApp.getAppStorage('color', function(value) {
      if (value !== null) {
        // set user color from storage
        backgroundColor = value;
      } else {
        // set default color
        backgrountColor = 'black';
      } 
    });

//
//  Start the flow of your application
//  ...

Ecwid allows your application to fully reside on client side and not use server side at all. You can authenticate the user, get store ID and access token, and manage the store data via Ecwid API right inside your app in Control panel without calling your server scripts.

By default, all applications are registered with this authentication type. The workflow can be described into the following steps:

1. Get store preferences and data
2. Initialize your application functionality

1. Get store preferences and data

For convenience, we provide a simple Ecwid JS SDK to authenticate the user and get access to the API. As soon as the JS SDK script is used, you can call the provided EcwidApp.getPayload() method to retrieve the user's store ID and access token as shown in the example code above. See also .getPayload() method specification.

Application storage can help you store and access user preferences without saving this information on your server. Ecwid JavaScript SDK can help you do that easy with built-in methods. See functions EcwidApp.getAppStorage, EcwidApp.setAppStorage and EcwidApp.getAppPublicConfig, EcwidApp.setAppPublicConfig in Ecwid Javascript SDK for more details.

2. Initialize your app functionality

After completing the first step, you know the store you are working with and you have the settings and other data specific to that store. Use use that information in your native application to start its standard workflow: load user preferences, render the user interface and so on.

Enhanced Security User Auth

In some cases you may need additional security for authenticating users: server-side app, integrations with 3rd party login systems and so on. That's when you should enable the Enhanced Security User Auth type for your Native app.

📘

All Native applications are registered with the Default User Auth, so you can start working on your application's tab right away without using server side.

If you need your app to be switched to Enhanced Security User Auth (server-side), please contact us and we will update your app.

The workflow of such applications can be divided into several steps:

1. Decrypt the payload from Ecwid
2. Get store specific data
3. Initialize your application functionality

1. Decrypt the payload from the Ecwid Control Panel

Let's say, you process user input and prepare the data to display in your app on your server and then pass this information to your application UI to be displayed in the user Control panel. In this case, you will need to authenticate user on server side of your application.

Example of the iframe URL call in server-side apps: https://www.example.com/my-app-iframe-page?payload=353035362c226163636573735f746f6b656e223a22776d6&app_state=orderId%3A%2012&cache-killer=13532

<?php
//
//  Get and decrypt the payload from Ecwid
//

// authenticate user in iframe page
function getEcwidPayload($app_secret_key, $data) {
  // Get the encryption key (16 first bytes of the app's client_secret key)
  $encryption_key = substr($app_secret_key, 0, 16);

  // Decrypt payload
  $json_data = aes_128_decrypt($encryption_key, $data);

  // Decode json
  $json_decoded = json_decode($json_data, true);
  return $json_decoded;
}

function aes_128_decrypt($key, $data) {
  // Ecwid sends data in url-safe base64. Convert the raw data to the original base64 first
  $base64_original = str_replace(array('-', '_'), array('+', '/'), $data);

  // Get binary data
  $decoded = base64_decode($base64_original);

  // Initialization vector is the first 16 bytes of the received data
  $iv = substr($decoded, 0, 16);

  // The payload itself is is the rest of the received data
  $payload = substr($decoded, 16);

  // Decrypt raw binary payload
  $json = openssl_decrypt($payload, "aes-128-cbc", $key, OPENSSL_RAW_DATA, $iv);
  //$json = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key, $payload, MCRYPT_MODE_CBC, $iv); // You can use this instead of openssl_decrupt, if mcrypt is enabled in your system

  return $json;
}

// Get payload from the GET and process it
$ecwid_payload = $_GET['payload'];
$client_secret = "0123abcd4567efgh1234567890"; // This is a dummy value. Place your client_secret key here. You received it from Ecwid team in email when registering the app 

$result = getEcwidPayload($client_secret, $ecwid_payload);

// Get store info from the payload
$token = $result['access_token'];
$storeId = $result['store_id'];
$lang = $result['lang'];
$viewMode = $result['view_mode'];

if (isset($result['public_token'])){
  $public_token = $result['public_token'];
}

// URL Encoded App state passed to the app
if (isset($_GET['app_state'])){
  $app_state = $_GET['app_state'];
}

//
//  Get store specific data
//

// Get store specific data from storage endpoint
$key = 'color';

$url = 'https://app.ecwid.com/api/v3/' .$storeId. '/storage/' .$key. '?token=' .$token;

$ch = curl_init();

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL,$url);

$curlResult = curl_exec($ch);
curl_close($ch);

$curlResult = (json_decode($curlResult));
$color = $curlResult -> {'value'};

  if ($color !== null ) {
    // set color from storage
    } else {
    // set default colors
  }

//
//  Start the flow of your application
//  ...
?>

public Dictionary<String, Object> DecodePayload(string payload)
{
    byte[] encryptionKey = System.Text.Encoding.ASCII.GetBytes(Environment.GetEnvironmentVariable("ECWID_CLIENT_SECRET").Substring(0, 16));

    string original = payload.Replace("-", "+").Replace("_", "/");

    byte[] decoded = Convert.FromBase64String(original.PadRight(original.Length + (4 - (original.Length % 4)), '='));

    string decodedData = Encoding.UTF8.GetString(decoded
    );

    Aes aes = new AesManaged
    {
        Key = encryptionKey,
        IV = Encoding.ASCII.GetBytes(decodedData.Substring(0, 16)),
        Mode = CipherMode.CBC
    };

    using (ICryptoTransform cipher = aes.CreateDecryptor())
    {
        string decrypted;

        using (MemoryStream memoryStream = new MemoryStream(decoded))
        {
            using (CryptoStream cryptoStream = new CryptoStream((Stream)memoryStream, cipher, CryptoStreamMode.Read))
            {
                using (StreamReader streamReader = new StreamReader((Stream)cryptoStream))
                {
                    decrypted = streamReader.ReadToEnd();
                }
            }
        }

        return JsonConvert.DeserializeObject<Dictionary<String, Object>>(decrypted.Substring(15));
    }

}

{
  "store_id": 1003,
  "lang": "en",
  "access_token":"xxxxxxxxxxxxxxxx",
  "view_mode":"PAGE",
  "public_token":"public_ASDlkDASmasdaslkdASkndasANJKLsAf"
}

Payload

The payload parameter is encrypted JSON string, which, when decrypted, has the following format:

Decryption of payload on your server

Ecwid uses AES-128 to encrypt the payload. The key is the first 16 symbols (128 bit) of your application secret key (client_secret). It is provided when you register an app with us. See a PHP example of decryption to get better idea on how to receive and decrypt the payload.

If you are using C# language

For correct payload decryption, create additional padding to make the payload a multiple of 4:

base64 = base64.PadRight(base64.Length + (4 - (base64.Length % 4)), '=');

2. Get store preferences and data

After completing the first step, you have store details and access to it using Ecwid REST API. Now you can get store-specific information from the storage endpoint or from your local database. The result of the payload decryption will be provided in an array $result, which you can use to get store ID, access token and language information about a store, that opened your Native app.

Application storage can help you store and access user preferences with the Ecwid REST API.

To save and get store-specific data in the storage endpoint, you can use cURL functionality in PHP or any other way that you prefer to access REST API endpoints. See how to retrieve the value of 'color' key in the application storage using cURL and process the result based on a response from API on the right.

3. Initialize your application functionality

Once you got all details that you need, you can start the standard planned workflow for your app and operate with Ecwid API using the details you got earlier.