Generating Session Tokens

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

Quick Example

TypeScript

import Ductape from '@ductape/sdk';

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

const result = await ductape.sessions.start({
  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

Java

import app.ductape.sdk.Ductape;
import app.ductape.sdk.core.EnvType;
import app.ductape.sdk.core.RequestContext;

RequestContext auth = new RequestContext(null, null, null, null, 'your-access-key');
Ductape ductape = new Ductape(EnvType.PRODUCTION, auth);

Map<String, Object> result = ductape.sessions.start(Map.of(
  "tag", "user-session",
  data: Map.of(
    "userId", "user_123",
    details: Map.of(
      "username", "johndoe",
      "email", "john@example.com"
    )
  )
));

System.out.println(result.token);        // Session token (format: tag:jwt)
System.out.println(result.refreshToken); // Refresh token
System.out.println(result.sessionId);    // Session ID
System.out.println(result.expiresAt);    // Expiration date

Go

import (
	"context"
	"github.com/ductape/ductape/sdk/go/core"
	ductapesdk "github.com/ductape/ductape/sdk/go/ductape"
)

auth := core.NewRequestContext("", "", "", "", 'your-access-key')
client, err := ductapesdk.New(core.EnvProduction, auth)
if err != nil {
	return err
}

result := client.sessions.start({
  "tag": "user-session",
  data: {
    "userId": "user_123",
    details: {
      "username": "johndoe",
      "email": "john@example.com",
    },
  },
});

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

.NET

using Ductape.Sdk;
using Ductape.Sdk.Core;

var auth = new RequestContext(null, null, null, null, 'your-access-key', null);
var ductape = new Ductape(EnvType.Production, auth);

var result = await ductape.sessions.start({
  ["tag"] = "user-session",
  data: {
    ["userId"] = "user_123",
    details: {
      ["username"] = "johndoe",
      ["email"] = "john@example.com",
    },
  },
});

Console.WriteLine(result.token);        // Session token (format: tag:jwt)
Console.WriteLine(result.refreshToken); // Refresh token
Console.WriteLine(result.sessionId);    // Session ID
Console.WriteLine(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

TypeScript

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

Java

Map<String, Object> session = ductape.sessions.start(Map.of(
  "tag", "checkout-session",
  data: Map.of(
    "userId", "user_456",
    details: Map.of(
      "email", "jane@example.com"
    )
  )
));

Go

session := client.sessions.start({
  "tag": "checkout-session",
  data: {
    "userId": "user_456",
    details: {
      "email": "jane@example.com"
    }
  }
});

.NET

var session = await ductape.sessions.start({
  ["tag"] = "checkout-session",
  data: {
    ["userId"] = "user_456",
    details: {
      ["email"] = "jane@example.com"
    }
  }
});

Session with rich user data

TypeScript

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

Java

Map<String, Object> session = ductape.sessions.start(Map.of(
  "tag", "user-session",
  data: Map.of(
    "userId", "user_789",
    details: Map.of(
      "username", "jsmith",
      "email", "jsmith@company.com",
      "role", "admin",
      "plan", "enterprise"
    )
  )
));

Go

session := client.sessions.start({
  "tag": "user-session",
  data: {
    "userId": "user_789",
    details: {
      "username": "jsmith",
      "email": "jsmith@company.com",
      "role": "admin",
      "plan": "enterprise"
    }
  }
});

.NET

var session = await ductape.sessions.start({
  ["tag"] = "user-session",
  data: {
    ["userId"] = "user_789",
    details: {
      ["username"] = "jsmith",
      ["email"] = "jsmith@company.com",
      ["role"] = "admin",
      ["plan"] = "enterprise"
    }
  }
});

Different sessions for different flows

TypeScript

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

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

Java

// Checkout flow session
Map<String, Object> checkoutSession = ductape.sessions.start(Map.of(
  "tag", "checkout-flow",
  data: Map.of( "userId", "user_123", details: Map.of( "cartId", "cart_456" ) )
));

// Support chat session
Map<String, Object> supportSession = ductape.sessions.start(Map.of(
  "tag", "support-chat",
  data: Map.of( "userId", "user_123", details: Map.of( "ticketId", "ticket_789" ) )
));

Go

// Checkout flow session
checkoutSession := client.sessions.start({
  "tag": "checkout-flow",
  data: { "userId": "user_123", details: { "cartId": "cart_456" } }
});

// Support chat session
supportSession := client.sessions.start({
  "tag": "support-chat",
  data: { "userId": "user_123", details: { "ticketId": "ticket_789" } }
});

.NET

// Checkout flow session
var checkoutSession = await ductape.sessions.start({
  ["tag"] = "checkout-flow",
  data: { ["userId"] = "user_123", details: { ["cartId"] = "cart_456" } }
});

// Support chat session
var supportSession = await ductape.sessions.start({
  ["tag"] = "support-chat",
  data: { ["userId"] = "user_123", details: { ["ticketId"] = "ticket_789" } }
});

Response

TypeScript

{
  token: string;        // Format: "tag:jwt" (e.g. "user-session:eyJhbGci...")
  refreshToken: string;
  expiresAt?: Date;
  sessionId?: string;
}

Java

Map.of(
  token: string;        // "Format", "tag:jwt" (e.g. "user-session:eyJhbGci...")
  refreshToken: string;
  expiresAt?: Date;
  sessionId?: string;
)

Go

{
  token: string;        // "Format": "tag:jwt" (e.g. "user-session:eyJhbGci...")
  refreshToken: string;
  expiresAt?: Date;
  sessionId?: string;
}

.NET

{
  token: string;        // ["Format"] = "tag:jwt" (e.g. "user-session:eyJhbGci...")
  refreshToken: string;
  expiresAt?: Date;
  sessionId?: string;
}

Field	Description
token	Session token (tag:jwt); use in verify() or pass to messaging/storage when needed
refreshToken	Long-lived token to refresh or resume sessions
expiresAt	When the access token expires
sessionId	Unique 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

TypeScript

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
}

Java

interface StartSessionInput Map.of(
  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
)

Go

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
}

.NET

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

• Sessions Overview
• Refreshing Sessions
• Decrypting Sessions