Skip to main content
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
{
  "dest": "api.smile.io",
  "sub": "<customer identifier>",
  "exp": "<time in seconds>"
}
  • dest — 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 IDFormatExample value
Smile Customer IDSmileCustomer:{id}SmileCustomer:304169228
Shopify Customer IDShopifyCustomer:{id}ShopifyCustomer:10733458
BigCommerce Customer IDBigCommerceCustomer:{id}BigCommerceCustomer:7398675
Custom Platform Customer IDCustomPlatformCustomer:{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_a5b85911214932b56b360ac956ddb392'

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' }
)