Skip to main content

Generating Session Tokens

Create session tokens to track user activity across your products using ductape.sessions.start().

Quick Example​

import Ductape from '@ductape/sdk';

const ductape = new Ductape({
  accessKey: 'your-access-key',
  env_type: 'prd', // optional
});

const result = await ductape.sessions.start({
  product: 'my-product',
  env: 'prd',
  tag: 'user-session',
  data: {
    userId: 'user_123',
    details: {
      username: 'johndoe',
      email: 'john@example.com',
    },
  },
});

console.log(result.token);        // Session token (format: tag:jwt)
console.log(result.refreshToken); // Refresh token
console.log(result.sessionId);    // Session ID
console.log(result.expiresAt);    // Expiration date

How It Works​

  1. product - Your product's unique identifier
  2. env - Which environment (dev, staging, prd)
  3. tag - A label for this session type (e.g., checkout-flow)
  4. data - User information and identifier

Examples​

Basic session​

const session = await ductape.sessions.start({
  product: 'ecommerce',
  env: 'prd',
  tag: 'checkout-session',
  data: {
    userId: 'user_456',
    details: {
      email: 'jane@example.com'
    }
  }
});

Session with rich user data​

const session = await ductape.sessions.start({
  product: 'dashboard',
  env: 'prd',
  tag: 'user-session',
  data: {
    userId: 'user_789',
    details: {
      username: 'jsmith',
      email: 'jsmith@company.com',
      role: 'admin',
      plan: 'enterprise'
    }
  }
});

Different sessions for different flows​

// Checkout flow session
const checkoutSession = await ductape.sessions.start({
  product: 'marketplace',
  env: 'prd',
  tag: 'checkout-flow',
  data: { userId: 'user_123', details: { cartId: 'cart_456' } }
});

// Support chat session
const supportSession = await ductape.sessions.start({
  product: 'marketplace',
  env: 'prd',
  tag: 'support-chat',
  data: { userId: 'user_123', details: { ticketId: 'ticket_789' } }
});

Response​

{
  token: string;        // Format: "tag:jwt" (e.g. "user-session:eyJhbGci...")
  refreshToken: string;
  expiresAt?: Date;
  sessionId?: string;
}
FieldDescription
tokenSession token (tag:jwt); use in verify() or pass to messaging/storage when needed
refreshTokenLong-lived token to refresh or resume sessions
expiresAtWhen the access token expires
sessionIdUnique session identifier

Best Practices​

  • Store tokens securely - Avoid exposing in logs or unencrypted storage
  • Use different tags - Create separate sessions for different flows
  • Include identifiers - Always provide a stable userId

Reference​

Parameters​

interface StartSessionInput {
  product: string;
  env: string;
  tag: string;
  data: Record<string, unknown>;  // Any JSON-serializable data (must match session schema)
  cache?: string;                 // Optional cache tag for idempotency
}

See Also​