Customer tokens

The SDK uses customer tokens to securely recognize and identify the currently logged-in customer during initialization. In practice, a customer token is a JSON Web Token (JWT) that has been generated securely on your platform’s backend and is signed using the HS256 algorithm with one of your account’s signing keys.

Customer tokens should never be generated on the frontend or in mobile app source code, as this risks exposing your signing key (a sensitive account secret) to the general public.

JWT headers

When generating a customer token, the values in the JWT header are constant and never change:

JSON

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

JWT payload

When generating a customer token, the payload of the JWT should be dynamic, e.g.

JSON

{
  "aud": "api.smile.io",
  "sub": "<customer identifier>",
  "exp": "<time in seconds>"
}

aud — The intended recipient of the JWT (should always be api.smile.io).
sub — An identifier for the currently logged-in customer (see notes below).
exp — When the JWT expires (recommendation: 5 minutes after JWT is generated).

Customer identifiers (`sub` values)

You can identify the logged-in customer by providing a sub claim in the payload of the JWT in one of the following supported formats. Choose the appropriate format based on which unique identifier you have available for the currently logged-in customer.

Type of ID	Format	Example value
Smile Customer ID	`SmileCustomer:{id}`	`SmileCustomer:304169228`
Shopify Customer ID	`ShopifyCustomer:{id}`	`ShopifyCustomer:10733458`
BigCommerce Customer ID	`BigCommerceCustomer:{id}`	`BigCommerceCustomer:7398675`
Custom Platform Customer ID	`CustomPlatformCustomer:{id}`	`CustomPlatformCustomer:937485`

The Custom Platform Customer ID format will only function for legacy merchants (pre-2018) on custom e-commerce platforms. All other merchants should use one of the other supported formats.

JWT generation example

# Generating a customer token from a Ruby backend
shopify_customer_id = '10733458'
signing_key = 'sig_1234567890abcdef1234567890abcdef'

payload = {
  aud: 'api.smile.io',
  sub: "ShopifyCustomer:#{shopify_customer_id}",
  exp: Time.now.to_i + 300 # Set expiry to 5 minutes
}

customer_token = JWT.encode(
  payload, signing_key, 'HS256', { typ: 'JWT' }
)

// Generating a customer token from a JS backend
import jwt from 'jsonwebtoken';

const shopifyCustomerId = '10733458';
const signingKey = 'sig_1234567890abcdef1234567890abcdef';

const payload = {
  aud: 'api.smile.io',
  sub: `ShopifyCustomer:${shopifyCustomerId}`,
  exp: Math.floor(Date.now() / 1000) + 300 // 5 minutes from now
};

const customerToken = jwt.sign(
  payload,
  signingKey,
  { algorithm: 'HS256', header: { typ: 'JWT' } }
);

Key concepts

Smile object

SDK resources

JWT headers

JWT payload

Customer identifiers (`sub` values)

JWT generation example

​JWT headers

​JWT payload

​Customer identifiers (sub values)

​JWT generation example

JWT headers

JWT payload

Customer identifiers (`sub` values)

JWT generation example