Tokens API

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "d_cf007a8b-19bc-46ad-8787-2915445b7b86",
    "dashboardSecret": "ds_f32f0b30-b7e1-40f9-ba6a-9804a5b9d635",
    "cls": { "name": "store_sales_primary", "params": { "tenant": "tenant_abc_123" } },
    "rcls": { "name": "region_filter", "params": { "state": ["California", "Nevada"] } }
  }'

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "p_1234567890abcdef",
    "projectSecret": "ps_abcdef1234567890",
    "endUserId": "user_123",
    "tokenExpiry": 1800
  }'

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "p_1234567890abcdef",
    "projectSecret": "ps_abcdef1234567890",
    "endUserEmail": "newuser@example.com",
    "tenantName": "Acme Corp",
    "autoCreateEndUser": true,
    "role": "VIEWER",
    "displayName": "John Doe",
    "tokenExpiry": 3600
  }'

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "p_1234567890abcdef",
    "projectSecret": "ps_abcdef1234567890",
    "endUserId": "user_123",
    "allowedSemanticDomains": ["sales_data", "marketing"],
    "initialDashboardId": "dashboard_main"
  }'

/**
 * Calendar context for timezone-aware date handling.
 */
export type CalendarContext = {
  /**
   * IANA timezone identifier (e.g., 'America/Chicago', 'Europe/London').
   * Defaults to 'UTC' if not specified or invalid.
   */
  tz: string;
  /**
   * First day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday).
   * Defaults to 1 (Monday, ISO standard).
   */
  weekStart?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  /**
   * Date anchor for relative date filters.
   * - 'now': Use current time (default)
   * - { iso: string }: Use fixed ISO date for reproducible views
   */
  anchor?: 'now' | { iso: string };
};
 
/**
 * Parameters for customizing token behavior and formatting.
 */
export type TokenParams = {
  /**
   * Legacy timezone field. Use calendarContext.tz instead.
   * @deprecated Use calendarContext for full timezone control.
   */
  timezone?: string;
  /**
   * Calendar context for timezone-aware date handling and week configuration.
   * Controls how relative date filters (e.g., "this week", "last month") are interpreted.
   */
  calendarContext?: CalendarContext;
  /**
   * Currency formatting preferences.
   */
  currencyFormat?: {
    /**
     * Locale identifier (e.g., 'en-US', 'fr-FR').
     */
    locale: string;
    /**
     * Currency code compliant with ISO 4217 (e.g., 'USD', 'EUR').
     */
    currency: string;
  };
};
 
/**
 * Defines a security policy that can be applied at connection or row level.
 */
export type TokenSecurityPolicy = {
  /**
   * Name of the policy (e.g., 'store_sales_primary', 'region_filter').
   */
  name: string;
  /**
   * Arbitrary parameters associated with the policy.
   * Examples:
   * // Single value
   * { tenant: 'tenant_abc_123' }
   * // Multiple values
   * { state: ['California', 'Nevada', 'Washington'] }
   */
  params: {
    [key: string]: string | number | string[] | number[];
  };
};
 
/**
 * UI and behavior configuration for the embedded dashboard.
 */
export type UIConfig = {
  /**
   * Enables self-service editing and lens creation by the end user. Legacy field. Use config.allowEdit instead.
   */
  allowEdit?: boolean;
  /**
   * Enables advanced mode features in the dashboard.
   * Defaults to true unless explicitly disabled.
   */
  showAdvancedMode?: boolean;
  /**
   * Enables the AI-powered dashboard assistant.
   * Defaults to true unless explicitly disabled.
   */
  showDashboardAssistant?: boolean;
};
 
/**
 * Main payload for generating a secure access token for a dashboard.
 */
export type DashboardTokenRequest = {
  /**
   * Identifier of the dashboard to be accessed.
   */
  dashboardId: string;
  /**
   * Secret key used for validating access to the dashboard.
   */
  dashboardSecret: string;
  /**
   * Token expiry duration in seconds.
   */
  tokenExpiry?: number;
  /**
   * Unique identifier of the tenant.
   */
  tenantId?: string;
  /**
   * Unique identifier of the tenant user accessing the dashboard.
   */
  endUserId?: string;
  /**
   * Email of the tenant user (for personalization, audit, or identification).
   */
  endUserEmail?: string;
  /**
   * Unique identifier of the org user accessing the dashboard.
   */
  orgUserId?: string;
  /**
   * Email of the org user (for personalization, audit, or identification).
   */
  orgUserEmail?: string;
  /**
   * Display name of the end user.
   */
  displayName?: string;
  /**
   * Enables self-service editing and lens creation by the end user.
   */
  allowEdit?: boolean;
  /**
   * Connection-level security policies.
   * Can be a single policy or an array of policies.
   */
  cls?: TokenSecurityPolicy[] | TokenSecurityPolicy;
  /**
   * Row-level security policies.
   * Can be a single policy or an array of policies.
   */
  rcls?: TokenSecurityPolicy[] | TokenSecurityPolicy;
  /**
   * Parameter overrides and preferences (e.g., formatting).
   */
  params?: TokenParams;
  /**
   * UI behavior and feature flags.
   */
  config?: UIConfig;
};
 
/**
 * Main payload for generating a project-level access token.
 */
export type ProjectTokenRequest = {
  /**
   * Must be 'project' for project tokens.
   */
  type: 'project';
  /**
   * Unique identifier of the project.
   */
  projectId: string;
  /**
   * Secret key used for validating access to the project.
   */
  projectSecret: string;
  /**
   * Token expiry duration in seconds.
   */
  tokenExpiry?: number;
  /**
   * Unique identifier of the tenant.
   */
  tenantId?: string;
  /**
   * Name of the tenant (alternative to tenantId).
   */
  tenantName?: string;
  /**
   * Unique identifier of the end user.
   */
  endUserId?: string;
  /**
   * Email of the end user.
   */
  endUserEmail?: string;
  /**
   * Unique identifier of the organization user.
   */
  orgUserId?: string;
  /**
   * Display name for the user.
   */
  displayName?: string;
  /**
   * Automatically create user if they don't exist.
   */
  autoCreateEndUser?: boolean;
  /**
   * Role for auto-created users ('VIEWER' or 'POWER_USER').
   */
  role?: 'VIEWER' | 'POWER_USER';
  /**
   * Initial dashboard to load.
   */
  initialDashboardId?: string;
  /**
   * Array of semantic domain IDs or names to restrict access.
   */
  allowedSemanticDomains?: string[];
  /**
   * Enables self-service editing.
   */
  allowEdit?: boolean;
  /**
   * Connection-level security policies.
   */
  cls?: TokenSecurityPolicy[] | TokenSecurityPolicy;
  /**
   * Row-level security policies.
   */
  rcls?: TokenSecurityPolicy[] | TokenSecurityPolicy;
  /**
   * Schema-level security policy.
   */
  sls?: string;
  /**
   * Parameter overrides and preferences.
   */
  params?: TokenParams;
  /**
   * UI behavior and feature flags.
   */
  config?: UIConfig;
};
 
/**
 * Combined token request type.
 */
export type TokenRequest = DashboardTokenRequest | ProjectTokenRequest;

{
  "cls": {
    "name": "store_sales_primary",
    "params": {
      "tenant": "tenant_abc_123"
    }
  }
}

{
  "rcls": {
    "name": "region_filter",
    "params": {
      "state": ["California", "Nevada", "Washington"]
    }
  }
}

{
  "cls": [
    {
      "name": "store_sales_primary",
      "params": { "tenant": "tenant_abc_123" }
    },
    {
      "name": "data_center_filter",
      "params": { "region": "us-west" }
    }
  ],
  "rcls": [
    {
      "name": "region_filter",
      "params": { "state": ["California", "Nevada"] }
    },
    {
      "name": "department_filter",
      "params": { "department": ["Sales", "Marketing"] }
    }
  ]
}

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "d_cf007a8b-19bc-46ad-8787-2915445b7b86",
    "dashboardSecret": "ds_f32f0b30-b7e1-40f9-ba6a-9804a5b9d635",
    "params": {
      "calendarContext": {
        "tz": "America/Chicago",
        "weekStart": 0
      }
    }
  }'

{
  "params": {
    "timezone": "America/New_York"
  }
}

{
  "params": {
    "calendarContext": {
      "tz": "America/New_York",
      "weekStart": 1,
      "anchor": "now"
    }
  }
}

class TokenManager {
  constructor() {
    this.token = null;
    this.expiry = null;
  }
 
  async getValidToken() {
    if (this.isTokenValid()) {
      return this.token;
    }
 
    return await this.generateNewToken();
  }
 
  isTokenValid() {
    return this.token && this.expiry && Date.now() < this.expiry;
  }
 
  async generateNewToken() {
    const response = await fetch('https://semaphor.cloud/api/v1/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        dashboardId: process.env.SEMAPHOR_DASHBOARD_ID,
        dashboardSecret: process.env.SEMAPHOR_DASHBOARD_SECRET,
        tokenExpiry: 3600,
      }),
    });
 
    const { data } = await response.json();
    this.token = data.accessToken;
    this.expiry = new Date(data.expiresAt).getTime();
 
    return this.token;
  }
 
  async invalidateToken() {
    if (this.token) {
      await fetch('https://semaphor.cloud/api/v1/invalidate-token', {
        method: 'POST',
        headers: { 'Authorization': `Bearer ${this.token}` },
      });
      this.token = null;
      this.expiry = null;
    }
  }
}

async function generateTenantToken(tenantConfig, userInfo) {
  const tokenRequest = {
    dashboardId: tenantConfig.dashboardId,
    dashboardSecret: tenantConfig.dashboardSecret,
    tenantId: tenantConfig.tenantId,
    endUserId: userInfo.id,
    endUserEmail: userInfo.email,
    allowEdit: tenantConfig.allowEdit,
    tokenExpiry: 7200,
  };
 
  // Add security policies if configured
  if (tenantConfig.securityPolicies) {
    tokenRequest.cls = tenantConfig.securityPolicies.cls;
    tokenRequest.rcls = tenantConfig.securityPolicies.rcls;
  }
 
  // Add user preferences
  if (userInfo.preferences) {
    tokenRequest.params = {
      currencyFormat: userInfo.preferences.currency,
      timezone: userInfo.preferences.timezone,
      locale: userInfo.preferences.locale,
    };
  }
 
  const response = await fetch('https://semaphor.cloud/api/v1/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(tokenRequest),
  });
 
  return response.json();
}

async function validateTokenPeriodically(token, interval = 300000) {
  // 5 minutes
  setInterval(async () => {
    try {
      const response = await fetch(
        'https://semaphor.cloud/api/v1/token/validate',
        {
          headers: { 'Authorization': `Bearer ${token}` },
        }
      );
 
      const { data } = await response.json();
 
      if (!data.valid) {
        console.warn('Token is no longer valid');
        // Handle token invalidation
      }
    } catch (error) {
      console.error('Token validation failed:', error);
    }
  }, interval);
}

async function generateTokenWithRetry(maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://semaphor.cloud/api/v1/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          dashboardId: process.env.SEMAPHOR_DASHBOARD_ID,
          dashboardSecret: process.env.SEMAPHOR_DASHBOARD_SECRET,
        }),
      });
 
      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error.message);
      }
 
      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
 
      // Wait before retrying (exponential backoff)
      await new Promise((resolve) =>
        setTimeout(resolve, Math.pow(2, attempt) * 1000)
      );
    }
  }
}