The Cello Referral Component contains sensitive data such as the identity of the referee, amounts of payouts and details regarding your user’s referral flow e.g. notifications. We use JWT (JSON Web token) to authenticate the user and authorize access to the data in the Referral Component. The expected flow is as follows:
  1. User logs into your system.
  2. Your backend provides your frontend code with a Cello JWT token.
  3. Your frontend code initializes the Referral Component with the token.

​
Generating the token

Keep your credentials safe. Never generate a token or store your secret on the client side!
To generate a valid Cello JWT token, you’ll need:
  1. Your Cello credentials: productId and product secret
  2. A productUserId that uniquely identifies the logged-in user
  3. A token signing library for your tech stack of choice. A good variety can be found in the JWT community
For more resources on server-side token generation see JWT community.

​
Credentials

You will require both productId and product secret to generate tokens for your users. You can find these in your Cello Portal: Portal Credentials Access Keys productId and PRODUCT_SECRET for Referral Component Cello JS

​
User identity

Cello requires a productUserId - a unique user identifier to be passed when initializing the Referral Component. This can be a user id that you already use to identify users in your product. It can also be any other new unique identifier you generate - the main requirement is that it is unique per user accross your application.
It is important that this ID is unique per user, rather than organisation.

​
JWT signing library

Regardless of the signing library you choose, make sure you use the HS512 signing algorithm: 
{
  "alg": "HS512",
  "typ": "JWT"
}

​
Token generation

Token payload attributes:
​
productId
string
required
Identifier of the product your users will refer
​
productUserId
string
required
Your logged-in user’s unique identifier within your system
​
iat
int
required
A token issuing Unix timestamp. Example: 1661876739
Note that some libraries do not require you to pass iat in the payload and default to the current time if you don’t.

​
Example

Example of token generation in a NodeJS backend with JavaScript: 
import { sign } from 'jsonwebtoken';

const tokenPayload = {
  productId: 'REPLACE_WITH_PRODUCT_ID',
  productUserId: 'REPLACE_WITH_CURRENT_USER_ID',
};
const secret = 'REPLACE_WITH_PRODUCT_SECRET';

const token = sign(tokenPayload, secret, {
  algorithm: 'HS512',
});
Creating a JWT token should always be done in your backend code and not in the browser!
Below is an example content of the generated JWT token. 
{
  "productId": "acme.com",
  "productUserId": "123456",
  "iat": 1662712365
}

​
Using the token

Finally, provide the server side-generated token in the token property when initializing the Referral Component. 
window.cello = window.cello || { cmd: [] };

window.cello.cmd.push(async (cello) => {
  await cello.boot({
    productId: "REPLACE_WITH_PRODUCT_ID",
    token: "REPLACE_WITH_TOKEN",
    ...otherOptions,
  });
});