What is token, and why should I use it?

Token

In short, access token is a time limited access key designed to safely transmit the user data in a such manner that recipient of the data can be sure that data received are exactly those that were sent. It allows you to use emalidate service using client side solutions (XHR, AJAX, FETCH, AXIOS) without compromising your API key.
Emalidate token is JWT (JSON Web Token), and you can generate it on your side with the following header, payload and signature:

HEADER:

{
    alg: "HS256",
    typ: "JWT"
}

PAYLOAD:

{
    iss: "YOUR_DOMAIN || emalidate.com",
    sub: "YOUR_USER_ID",
    iat: NUMERIC_DATE_OF_TOKEN_GENERATION_IN_SECONDS,
    exp: NUMERIC_DATE_OF_TOKEN_EXPIRATION_IN_SECONDS,
    jti: "TOKEN_UNIQUE_ID",
    kid: "API_KEY_ID"
}

SIGNATURE:

Your token should be signed using HMAC SHA256 with the secret phrase you defined in your dashboard:

HMACSHA256(
    base64UrlEncode(HEADER) + "." +
    base64UrlEncode(PAYLOAD),
    YOUR_SECRET_PHRASE
)

Final token looks like this:

base64UrlEncode(HEADER) + "." +
base64UrlEncode(PAYLOAD) + "." +
base64UrlEncode(SIGNATURE)

Payload values explained:

iss should have a value of your domain name or "emalidate.com"
sub should be your Emalidate user ID
kid is a Key ID of your Emalidate API key. Make sure not to use a value of API key here.
jit any unique identification string made specifically this particular token
iat is UNIX timestamp value of the token creation date/time
exp is UNIX timestamp value of the token expiration date/time

Values for YOUR_USER_ID, API_KEY_ID and YOUR_SECRET_PHRASE are displayed using the command "View token generating data" in your dashboard

More info about JWT can be found at https://www.rfc-editor.org/rfc/rfc7519.html#page-10 and https://jwt.io/

generateToken function

PHP

Python v2

Python v3

Node

<?php
function base64urlEncode($input){
    return rtrim(strtr(base64_encode($input), '+/', '-_'), '=');
}

function generateToken($userId, $secret, $keyId, $duration = 300)
{
    $issued = time();
    $expiry = $issued + $duration;
    $headers = array('alg' => 'HS256', 'typ' => 'JWT');
    $payload = array(
        'iss' => 'emalidate.com', //replace with your own domain
        'sub' => $userId,
        'iat' => $issued,
        'exp' => $expiry,
        'jti' => hash('MD5', $userId . random_bytes(11)),
        'kid' => $keyId
    );
    $headersEncoded =
        base64urlEncode(json_encode($headers));

    $payloadEncoded =
        base64urlEncode(json_encode($payload));

    $signatureEncoded =
        base64urlEncode(hash_hmac('SHA256', "$headersEncoded.$payloadEncoded", $secret, true));

    return "$headersEncoded.$payloadEncoded.$signatureEncoded";
}

// Usage: generateToken(userId, secret, keyId, duration)

import base64
import json
import hmac
import hashlib
import random
import string 
import calendar

from datetime import datetime


def base64urlEncode(input):
    return base64.b64encode(input).replace( '+', '-').replace('/', '_').rstrip('=') 


def generateToken(userId, secret, keyId, duration = 300):
    now = datetime.utcnow()
    issued = int(calendar.timegm(now.timetuple()))
    expiry = issued+duration
    headers = {
        "alg": "HS256",
        "typ": "JWT"
    }
    payload = { 
                'iss': 'emalidate.com', #replace with your own domain
                'sub': userId,
                'iat': issued,
                'exp': expiry,
                'jti': hashlib.md5(userId + ''.join(random.choice(string.ascii_lowercase) for i in range(11))).hexdigest(),
                'kid': keyId
               }
    headersEncoded = str(base64urlEncode(json.dumps(headers)))
    payloadEncoded = str(base64urlEncode(json.dumps(payload)))
    signatureEncoded = str(base64urlEncode(hmac.new(secret, headersEncoded + '.' + payloadEncoded, hashlib.sha256).digest()))
    token = headersEncoded + '.' + payloadEncoded + '.' + signatureEncoded
    return token

# Usage: generateToken(userId, secret, keyId, duration)

import base64
import json
import hmac
import hashlib
import random
import string
from datetime import datetime


def base64urlEncode(input):
  if isinstance(input, str):
      input = input.encode('utf-8')
  return base64.b64encode(input).decode('utf-8').replace('+', '-').replace('/', '_').rstrip('=')


def generateToken(userId, secret, keyId, duration=300):
    issued = int(datetime.now().timestamp())
    expiry = issued + duration
    headers = {
        "alg": "HS256",
        "typ": "JWT"
    }
    payload = {
        'iss': 'emalidate.com',  # replace with your own domain
        'sub': userId,
        'iat': issued,
        'exp': expiry,
        'jti': hashlib.md5((userId + ''.join(random.choice(string.ascii_lowercase) for i in range(11))).encode('utf-8')).hexdigest(),
        'kid': keyId
    }
    headersEncoded = base64urlEncode(json.dumps(headers))
    payloadEncoded = base64urlEncode(json.dumps(payload))
    # HMAC requires bytes, so we convert the strings to bytes
    signatureEncoded = base64urlEncode(hmac.new(secret.encode('utf-8'), (headersEncoded + '.' + payloadEncoded).encode('utf-8'), hashlib.sha256).digest())
    token = headersEncoded + '.' + payloadEncoded + '.' + signatureEncoded
    return token

# Usage: generateToken(userId, secret, keyId, duration)

const crypto = require('crypto');
const base64url = require('base64url');

function generateToken(userId, secret, keyId, duration = 300) {
    const issued = Math.floor(Date.now() / 1000);
    const expiry = issued + duration;
    const headers = {
        alg: "HS256",
        typ: "JWT"
    };
    const payload = {
        iss: "emalidate.com", //replace with your own domain
        sub: userId,
        iat: issued,
        exp: expiry,
        jti: crypto.createHash('md5').update(userId + Math.random().toString(36).substring(2)).digest('hex'),
        kid: keyId
    }
    const headersEncoded = base64url(JSON.stringify(headers));
    const payloadEncoded = base64url(JSON.stringify(payload));
    const signatureEncoded = base64url.fromBase64(crypto.createHmac('sha256', secret).update(`${headersEncoded}.${payloadEncoded}`).digest("base64"));
    return `${headersEncoded}.${payloadEncoded}.${signatureEncoded}`;
}

// Usage: generateToken(userId, secret, keyId, duration)