Customer Session Tokens (JWE)

​

Overview

• Generated on your backend only, using your SecretKey.
• Contains the customer’s unique identifier and optional metadata.
• Short-lived: expires with the customer’s session.
• Used together with playerUniqueId on the client side to securely load Gameball widgets and SDKs.

• Token format and claims.
• Reference generation code in multiple languages.
• When to generate / refresh / drop the token in web and mobile flows.

​

1. Token Format & Claims

• Inner JWT (JWS): signed with HS256 using your SecretKey.
• Outer JWE: encrypts that JWT using A256KW + A256CBC-HS512, again with your SecretKey.

​

1.1 Claims

{
  "customerId": "123456",
  "customerEmail": "[email protected]",
  "customerMobile": "+201234567890",
  "exp": 1714742400
}

• customerId (required):
  Your unique identifier for the customer (must match playerUniqueId you send to the SDK).
• customerEmail (optional)
• customerMobile (optional)
• exp (required):
  Expiry timestamp (Unix seconds). Should match or be shorter than the session duration in your own auth system.

​

2. Cryptography Details

​

Signing:

• Algorithm: HS256 (HMAC SHA-256)
• Key: your Gameball SecretKey

​

Encryption:

• Key management algorithm: A256KW
• Content encryption algorithm: A256CBC-HS512
• Key: same SecretKey (symmetric key)

​

Key length:

​

3. Reference Implementations

​

3.1 C# (.NET)

using System;
using System.Collections.Generic;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;
using Microsoft.IdentityModel.Tokens;

public static class GameballTokenHelper
{
    public const string ClaimCustomerId    = "customerId";
    public const string ClaimCustomerEmail = "customerEmail";
    public const string ClaimCustomerMobile= "customerMobile";

    public static string GenerateCustomerSessionToken(
        string secretKey,
        DateTime expiresAtUtc,
        string customerId,
        string? email = null,
        string? mobile = null)
    {
        var claims = new Dictionary<string, object>
        {
            { ClaimCustomerId, customerId }
        };

        if (!string.IsNullOrWhiteSpace(email))
            claims.Add(ClaimCustomerEmail, email);

        if (!string.IsNullOrWhiteSpace(mobile))
            claims.Add(ClaimCustomerMobile, mobile);

        return GenerateJWEToken(secretKey, expiresAtUtc, claims);
    }

    public static string GenerateJWEToken(
        string secretKey,
        DateTime? expiration,
        IDictionary<string, object> claims)
    {
        var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secretKey));

        var signingCredentials = new SigningCredentials(
            securityKey,
            SecurityAlgorithms.HmacSha256);

        var encryptingCredentials = new EncryptingCredentials(
            securityKey,
            SecurityAlgorithms.Aes256KW,
            SecurityAlgorithms.Aes256CbcHmacSha512);

        var tokenDescriptor = new SecurityTokenDescriptor
        {
            Subject = new ClaimsIdentity(),
            SigningCredentials = signingCredentials,
            EncryptingCredentials = encryptingCredentials,
            Claims = (IDictionary<string, object>)claims,
            Expires = expiration
        };

        var handler = new JwtSecurityTokenHandler();
        var token = handler.CreateJwtSecurityToken(tokenDescriptor);

        return token.RawData;
    }
}

​

3.2 Node.js / TypeScript with jose

import { SignJWT, CompactEncrypt } from 'jose';

const encoder = new TextEncoder();

export async function generateGameballSessionToken(options: {
  secretKey: string;
  customerId: string;
  email?: string;
  mobile?: string;
  expiresInSeconds: number;
}): Promise<string> {
  const { secretKey, customerId, email, mobile, expiresInSeconds } = options;

  const keyBytes = encoder.encode(secretKey);
  const now = Math.floor(Date.now() / 1000);
  const exp = now + expiresInSeconds;

  const claims: Record<string, any> = {
    customerId,
    exp
  };

  if (email)  claims.customerEmail  = email;
  if (mobile) claims.customerMobile = mobile;

  // Signed JWT (JWS)
  const jws = await new SignJWT(claims)
    .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
    .sign(keyBytes);

  // Encrypted JWE
  const plaintext = encoder.encode(jws);

  const jwe = await new CompactEncrypt(plaintext)
    .setProtectedHeader({
      alg: 'A256KW',
      enc: 'A256CBC-HS512'
    })
    .encrypt(keyBytes);

  return jwe;
}

​

3.3 Python with jwcrypto

from datetime import datetime, timedelta, timezone
from jwcrypto import jwt, jwk
import base64

def _build_symmetric_key(secret_key: str) -> jwk.JWK:
    # JWK 'k' must be base64url-encoded bytes, so we encode the secret key
    k = base64.urlsafe_b64encode(secret_key.encode("utf-8")).rstrip(b"=")
    return jwk.JWK(kty='oct', k=k.decode('ascii'))

def generate_gameball_session_token(
    secret_key: str,
    customer_id: str,
    email: str | None = None,
    mobile: str | None = None,
    expires_in_seconds: int = 7200,
) -> str:
    key = _build_symmetric_key(secret_key)

    now = datetime.now(timezone.utc)
    exp = now + timedelta(seconds=expires_in_seconds)

    claims = {
        "customerId": customer_id,
        "exp": int(exp.timestamp())
    }

    if email:
        claims["customerEmail"] = email
    if mobile:
        claims["customerMobile"] = mobile

    # Signed token (JWS)
    signed = jwt.JWT(
        header={"alg": "HS256", "typ": "JWT"},
        claims=claims
    )
    signed.make_signed_token(key)

    # Encrypted token (JWE)
    encrypted = jwt.JWT(
        header={"alg": "A256KW", "enc": "A256CBC-HS512"},
        claims=signed.serialize()
    )
    encrypted.make_encrypted_token(key)

    return encrypted.serialize()

​

4. Web Flows – When to Generate the Token

​

4.1 Login

1. User submits login credentials.
2. Backend validates credentials.
3. Backend:
   • Creates/refreshes your own app session (cookie/JWT/etc.).
   • Calls generateGameballSessionToken with:
     • customerId = the same ID as playerUniqueId.
     • email / mobile if you want them in the token.
     • expiresAt aligned with your own session.
4. Backend returns the Gameball session token to frontend, e.g.:
   • Embedded in login response JSON, or
   • Via a dedicated “get Gameball token” endpoint that the frontend calls immediately after login.
5. Frontend stores the token in memory (or short-lived storage, not long-term persistence) and initializes the widget with:
   • APIKey
   • playerUniqueId = your customer ID
   • sessionToken = the JWE you generated.

​

4.2 Session extension / refresh

1. Frontend calls your backend to refresh the app session.
2. If you extend the app session, the backend:
   • Generates a new Gameball session token with a new exp.
3. Frontend replaces the old token and:
   • Re-initializes the widget if needed, or
   • Uses SDK APIs to update the token if supported.

​

4.3 Token expiry while the user is active

• Frontend tracks the token’s exp (provided by your backend along with the token).
• A bit before expiry (e.g. 5 minutes), frontend calls backend for a new token.

• If Gameball responds with an “expired token” error:
  • Frontend calls your backend to get a new token.
  • Re-initializes the widget.

​

4.4 Logout

1. Frontend clears:
   • Your own session (cookies/local storage).
   • Any in-memory Gameball session token.

​

5. Mobile Flows – When to Generate the Token

​

5.1 Mobile login

1. User logs into your mobile app.
2. App calls backend with credentials.
3. Backend:
   • Issues your app’s auth token (JWT, opaque token, etc.).
   • Generates Gameball session token for that customer.
4. Backend returns both to the app.
5. Mobile app:
   • Stores your auth token as usual (Keychain/Secure Storage).
   • Stores Gameball session token in memory or secure storage (but treat it as short-lived).
   • Initializes the Gameball SDK with:
     • APIKey
     • playerUniqueId
     • sessionToken.

​

5.2 App resume / foreground

1. When the app resumes, check:
   • Your auth token is still valid.
   • The Gameball session token has not expired (you can have the backend expose its exp or simply call backend to refresh).
2. If the Gameball token is expired or close to expiring:
   • Call backend to issue a new token for the current customer.
   • Update the SDK with the new token.

​

5.3 Token rotation on account switch

1. When user logs out:
   • Delete both your app’s auth token and any stored Gameball session token.
2. When a new user logs in:
   • Repeat login flow and generate a new Gameball session token for that new customerId.
   • Reinitialize Gameball SDK with the new playerUniqueId + new sessionToken.

​

6. Using the Token in SDK Configuration

• playerUniqueId — your stable customer identifier.
• The session token you generated.

GbSdk.init({
  APIKey: '<YOUR_API_KEY>',
  playerUniqueId: currentUser.id,     // must match customerId in token
  lang: 'en',
  sessionToken: gameballSessionToken, // JWE from your backend
  // other options...
});

​

7. Error Handling Patterns

• Expired.
• Missing.
• Invalid (bad key, tampering, etc.).

​

Recommended behavior:

• Treat as a signal to refresh.
• Frontend/mobile calls backend to get a new session token (if the user is still authenticated in your system).

• Log the event in your backend or monitoring system.
• Ask the user to re-authenticate if needed.

• Don’t initialize the widget.
• Show a generic “loyalty is temporarily unavailable” message instead of partially loading.

​

8. Quick Checklist for Session Tokens

• Token is generated only on the backend.
• Token uses customerId, matches playerUniqueId.
• Token includes an exp that matches your app session.
• Token signed (HS256) and encrypted (A256KW + A256CBC-HS512) with your SecretKey.
• No SecretKey is ever exposed in JS/mobile.
• Web and mobile flows generate/refresh/drop tokens at:
  • Login
  • Session extension
  • Long active sessions (expiry handling)
  • Logout
  • Account switch

​

Related Documentation