SaaSquatch Help Center

JSON Web Tokens are used as part of Signed Requests with squatch.js and Open Endpoints. They are used to validate the data being supplied to Referral SaaSquatch.

What is a JWT?

A JWT is an open standard for securely sharing information as a JSON object. JWTs are small enough to be used in a GET or POST parameter or an HTTP header and because they are digitally signed the information inside can be trusted. This allows us to use a JWT like a checksum to verify that the squatch.js init parameters are correct, but with the convenience of using a library to generate the JWT.

How do I generate a JWT?

JWTs can easily be generated using one of the libraries available. There are even more libraries in even more languages available on GitHub in addition to the ones recommended by

Example: Building the JWT

1. Collect the Data Object

Whether you are using a JWT with squatch.js, the Open Endpoints, or the Mobile SDK you will need to start with the data object that you are trying to sign.

For Open Endpoint and squatch.js V2 calls the data might look like:
    "id": "abc_123",
    "accountId": "abc_123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "",
    "referable": true,
    "locale": "en_US",
    "referralCode": "JOHNDOE",
    "imageUrl": "",
    "paymentProviderId": null,
"referredBy": { "code": "JANEDOE", "isConverted": true } }
For squatch.js V1 the data might look like:
  "tenant_alias": "test_aaaexampleaaa",
  "account_id": "abc_123",
  "user_id": "abc_123",
  "email": "",
  "first_name": "John",
  "last_name": "Doe",
  "payment_provider_id": null,
  "referral_code": "JANEDOE",
  "user_referral_code": "JOHNDOE"

Please Note:
For authenticating requests where there is no id or accountId, the data object to be signed should be "allowAnonymous": true. See our createCookieUser Method with Signed Requests On in Version 2 Advanced Use Cases for more details.

2. Assemble the JWT payload

The JWT payload structures the data trying to be signed as follows:

Please Note:
tenantAlias - do not include in the JWT payload in either squatch.js v2 or v1
locale, mode, imageUrl - do not include in the JWT payload in squatch.js v1

For Open Endpoint and squatch.js V2 calls:
    "id": "abc_123",
    "accountId": "abc_123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "",
    "referable": true,
    "referralCode": "JOHNDOE",
    "paymentProviderId": null,
"referredBy": { "code": "JANEDOE", "isConverted": true } } }
For squatch.js V1 and the mobile URL widget calls:
  "user": {
    "id": "abc_123",
    "accountId": "abc_123",
    "email": "",
    "firstName": "John",
    "lastName": "Doe",
    "paymentProviderId": null,
    "accountStatus": "PAID",
    "referralCode": "JANEDOE",
    "userReferralCode": "JOHNDOE"

3. Sign the Payload

Use your chosen library to build the JWT with the payload, and sign it with your tenant's API key.

Test mode vs. live mode - Your Referral SaaSquatch program provides both a live and test mode. Each of these tenants provides an independant API key. Make sure to use the correct API key for call you are trying to sign.

using System.Collections.Generic;
    using System.Text;
    using Jose;

    namespace JWTExample
        class Program
            public static string buildJWT(string secret, string accountId, string userId, string email, string firstName, string lastName, long expiryDate, string referralCode, string userReferralCode, string accountStatus, string userImage)
                var userPayload = new Dictionary<string, object>()
                  { "id", userId },
                  { "accountId", accountId },
                  { "firstName", firstName },
                  { "lastName", lastName },
                  { "email", email },
                  { "userReferralCode", userReferralCode },
                  { "referralCode", referralCode },
                  { "userImage", userImage},
                  { "accountStatus", accountStatus }

                var payload = new Dictionary<string, object>()
                  { "user", userPayload },
                  { "exp", expiryDate } //optional date in seconds since the epoch

                //the encoding must match the encoding of your secret, UTF8 is just an example
                var byteSecret = Encoding.UTF8.GetBytes(secret);

                return Jose.JWT.Encode(payload, byteSecret, JwsAlgorithm.HS256);
require 'jwt'

    def buildJWT(secret, userId, accountId, email, firstName, lastName, referralCode, userReferralCode, accountStatus, userImage, expiryDate)
        secret = 'Referral SaaSquatch API key'
        return payload = JWT.encode({
        user: {
        id: userId,
        accountId: accountId,
        firstName: firstName,
        lastName: lastName,
        referralCode: referralCode,
        userReferralCode: userReferralCode,
        accountStatus: accountStatus,
        userImage: userImage
        exp: expiryDate #optional date in seconds since the epoch
        }, secret)
import java.util.HashMap;
import java.util.Map;

import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JOSEObjectType;
import com.nimbusds.jose.JWSAlgorithm;
import com.nimbusds.jose.JWSHeader;
import com.nimbusds.jose.crypto.MACSigner;
import com.nimbusds.jwt.JWTClaimsSet;
import com.nimbusds.jwt.SignedJWT;

public class JWTExample {

    public static String buildJWT(String secret, String accountId, String userId, String email,
            String firstName, String lastName, Long expiryDate, String referralCode, String userReferralCode,
            String accountStatus, String userImage) {
        // build user object
        final Map<String, Object> userMap = new HashMap<String, Object>();
        userMap.put("id", userId);
        userMap.put("accountId", accountId);
        userMap.put("firstName", firstName);
        userMap.put("lastName", lastName);
        userMap.put("email", email);
        userMap.put("userReferralCode", userReferralCode);
        userMap.put("referralCode", referralCode);
        userMap.put("userImage", userImage);
        userMap.put("accountStatus", accountStatus);

        // standard header
        final JWSHeader header = new JWSHeader.Builder(JWSAlgorithm.HS256)
        final JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
                .claim("user", userMap)
                .claim("exp", expiryDate) // optional nullable date in seconds since the epoch
        final SignedJWT jwt = new SignedJWT(header, claimsSet);
        try {
            jwt.sign(new MACSigner(secret));
        } catch (JOSEException e) {
            // This will happen if your secret is shorter than 256 bits.
            // If you are using your tenant API key, you won't need to worry about it.
            throw new RuntimeException(e);
        return jwt.serialize();
use \Firebase\JWT\JWT;

    function buildJWT($secret, $userId, $accountId, $email, $firstName, $lastName, $expiryDate, $referralCode, $userReferralCode, $accountStatus, $userImage) {
        //build user object
        $payload = array(
        "user" => array(
          "id" => $userId,
          "accountId" => $accountId,
          "firstName" => $firstName,
          "lastName" => $lastName,
          "email" => $email,
          "userReferralCode" => $userReferralCode,
          "referralCode" => $referralCode,
          "userImage" => $userImage,
          "accountStatus" => $accountStatus,
        "exp" => $expiryDate //optional date in seconds since the epoch

        //the encoder defaults to HS256, no need to specify an algorithm
        return JWT::encode($payload, $secret);
import jwt

    def buildJWT(secret, userId, accountId, email, firstName, lastName, referralCode, userReferralCode, accountStatus, userImage, expiryDate):
    return jwt.encode({
    'user': {
        'id': userId,
        'accountId': accountId,
        'firstName': firstName,
        'lastName': lastName,
        'referralCode': referralCode,
        'userReferralCode': userReferralCode,
        'accountStatus': accountStatus,
        'userImage': userImage
    'exp': expiryDate #optional date in seconds since the epoch
    }, secret, algorithm='HS256')

4. Include the JWT


For use with you squatch.js your JWT should be included as follows:

_sqh.push(['init', {
      tenant_alias: 'test_aaaexampleaaa',
      account_id: 'a5678',
      payment_provider_id: null,
      user_id: 'u1234',
      email: '',
      first_name: 'Joe',
      last_name: 'Tester'
      jwt: 'eyJhbGciOi.eyJzdWIiOixY.TJA95OrM' // <-- Add the JWT to your init call
Open Endpoint API Call

Note - Open Endpoint API calls made from a server should be signed with your tenant's API key. Only Open Endpoint calls from a client should be signed with a JWT.

For use with an Open Endpoint API call the JWT should be included in the API call as a header with the key X-SaaSquatch-User-Token.

cURL uses the -H flag to pass an extra header. You may specify any number of extra headers.

curl -X POST{tenant_alias}/open/account/{accountId}/user/{userId} \
-H "X-SaaSquatch-User-Token: eyJhbGciOi.eyJzdWIiOixY.TJA95OrM" \
-H "Content-Type: application/json" \
-d '{
    "id": "u1234",
    "accountId": "a5678",
    "email": "",
    "firstName": "Joe",
    "lastName": "Testerson",
    "locale": "en_US",
    "referralCode": "JOETESTERSON"
Mobile SDK

For use with a Mobile SDK call the JWT should be included in the userInfo object as follows:

let userInfo: [String: AnyObject] =
    "id": "10001110101",
    "accountId": "10001110101",
    "email": "",
    "firstName": "Claire",
    "lastName": "Fraser",
    "locale": "en_US",
    "referralCode": "CLAIREFRASER",
    "secret": "eyJhbGciOi.eyJzdWIiOixY.TJA95OrM",

Details about which library to use to sign JWTs in mobile apps can be found here.

Additional Resources

Further information about Signed Requests for squatch.js, Open Endpoints, and the Mobile SDK is available. Here you can find out about case-specific details about parameters to exclude and how to add the JWL to the call.