Authentication in native apps

Native apps can help you show store data, like orders or products. To do that, your application will need to know:

  • Store ID of a merchant
  • Access token for the Ecwid REST API
  • Language of the Ecwid Control Panel
  • Application state to initialize the app with (optional)

Ecwid will pass this data to your application as an encrypted payload as soon as it is opened in Ecwid Control panel.

Authentication flow

In the auth process, Ecwid calls your iframe URL like this:

https://www.example.com/my-app-iframe-page?payload=353035362c226163636573735f746f6b656e223a22776d6&app_state=orderId%3A%2012&cache-killer=13532

Where the ?payload=353035362c226163636573735f746f6b656e223a22776d6 is the payload part containing encrypted store information described below.

Your application needs an access token for the Ecwid REST API to read and modify Ecwid store orders, products, and other information.

📘

All Native applications are registered with that Authentication flow, so you can start working on your application's tab right away using server-side auth.

If your app uses an old Auth without an encrypted payload passed to your server, please contact us and we will update your app.

The process of getting an access token is described below:

The workflow can be divided into three 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

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 = "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"
}
NameTypeDescription
payloadstringEncrypted JSON string containing the authentication information (see the details below)
cache-killerstringRandom string preventing caching on your server
app_statestringOptional URL Encoded app state passed to the app in the URL

Payload

The payload parameter is an encrypted JSON string, which has the following format in decrypted array state:

NameTypeDescription
store_idnumberEcwid store ID
langstringUser language (which is currently set in their Control Panel). Use this parameter to translate your application UI to the user language.
access_tokenstringSecure oAuth token (secret_token) for Ecwid REST API
public_tokenstringPublic oAuth token (public_token) for Ecwid REST API
view_modestringMode used to display the application interface: POPUP, PAGE or INLINE. PAGE is a default mode when app is displayed in a separate tab in Ecwid Control Panel, POPUP is used when the app UI is displayed in a popup on any page of Ecwid CP, INLINE type is used for displaying the interface inside an element on a page where other elements are also present

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 understand receiving and decrypting the payload better.

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 you prefer to access REST API endpoints.

3. Initialize your application functionality

Once you have all the details that you need, you can start the standard planned workflow for your app and operate with Ecwid REST API in the background.