Referral 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 JWT.io.

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 a squatch.js init call this data might look like:

{
  "tenant_alias": "test_aaaexampleaaa",
  "account_id": "a5678",
  "payment_provider_id": null,
  "user_id": "u1234",
  "email": "joe@example.com",
  "first_name": "Joe",
  "last_name": "Tester",
}

For an Open Endpoint API call the data might look like:

{
    "id": "u1234",
    "accountId": "a5678",
    "email": "joe@example.com",
    "firstName": "Joe",
    "lastName": "Testerson",
    "locale": "en_US",
    "referralCode": "JOETESTERSON"
}

2. Assemble the JWT payload

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

{
    "user": {
        "id": "u1234",
        "accountId": "a5678",
        "firstName": "Joe",
        "lastName": "Tester",
        "email": "joe.tester@example.com",
        "paymentProviderId": null
    }
}

3. Sign the Payload

Use your chosen library to build the JWT with the payload, and sign it with your 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()
                {
                  { "id", userId },
                  { "accountId", accountId },
                  { "firstName", firstName },
                  { "lastName", lastName },
                  { "email", email },
                  { "userReferralCode", userReferralCode },
                  { "referralCode", referralCode },
                  { "userImage", userImage},
                  { "accountStatus", accountStatus }
                };

                var payload = new Dictionary()
                {
                  { "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)
    end
import com.auth0.jwt.Algorithm;
    import com.auth0.jwt.JWTSigner;
    import com.auth0.jwt.JWTSigner.Options;

    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
        Map userMap = new HashMap();
        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);

        //create token
        JWTSigner signer = new JWTSigner(secret);
        Map claims = new HashMap();
        claims.put("user", userMap);
        if (expiryDate != null) {
        claims.put("exp", expiryDate.longValue()); //optional date in seconds since the epoch
        }
        Options options = new Options();
        options.setAlgorithm(Algorithm.HS256);
        String signedToken = signer.sign(claims, options);
        return signedToken;
    }
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

squatch.js

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: 'joe.tester@example.com',
      first_name: 'Joe',
      last_name: 'Tester'
      jwt: 'eyJhbGciOi.eyJzdWIiOixY.TJA95OrM' // <-- Add the JWT to your init call
}]);
Open Endpoint API Call

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 https://app.referralsaasquatch.com/api/v1/{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": "Joe@example.com",
    "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": "claire@lallybroch.com",
    "firstName": "Claire",
    "lastName": "Fraser",
    "locale": "en_US",
    "referralCode": "CLAIREFRASER",
    "secret": "eyJhbGciOi.eyJzdWIiOixY.TJA95OrM",
]

Troubleshooting

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.

Looking for something special?

Still couldn't find it?