Security Settings

Overview

Security settings let you configure store-wide policies that apply to all team members and API access. Enforce two-factor authentication, restrict access by IP address, set session timeout rules, and schedule automatic API key rotation. Changes take effect immediately and are logged in the audit trail.

Get Settings

Retrieve the current security configuration for your store. The response includes all active policies, enforcement status, and the last time settings were modified.

const whale = new WhaleClient("wk_live_...");

const settings = await whale.security.get();

// Response
{
  "object": "security_settings",
  "store_id": "store_a1b2c3d4",
  "two_factor": {
    "required": true,
    "methods": ["totp", "sms"],
    "enforcement_date": "2026-02-01T00:00:00.000Z",
    "compliant_members": 8,
    "non_compliant_members": 0
  },
  "ip_allowlist": {
    "enabled": true,
    "entries": 3,
    "applies_to": ["api", "dashboard"]
  },
  "session_policy": {
    "timeout_minutes": 480,
    "max_concurrent_sessions": 3,
    "require_re_auth_for_sensitive": true
  },
  "password_policy": {
    "min_length": 12,
    "require_uppercase": true,
    "require_number": true,
    "require_special": true,
    "max_age_days": 90
  },
  "api_key_rotation": {
    "enabled": true,
    "interval_days": 90,
    "grace_period_hours": 48,
    "next_rotation": "2026-04-01T00:00:00.000Z"
  },
  "updated_at": "2026-03-08T12:00:00.000Z",
  "updated_by": "user_d4e5f6a7"
}

Enforce 2FA

Require all team members to enable two-factor authentication. When enforced, members without 2FA configured will be prompted to set it up on their next login. You can choose which methods to allow — TOTP (authenticator app) and SMS.

await whale.security.update({
  two_factor: {
    required: true,
    methods: ["totp", "sms"],
    grace_period_hours: 72  // time for members to comply
  }
});

// Response
{
  "object": "security_settings",
  "two_factor": {
    "required": true,
    "methods": ["totp", "sms"],
    "enforcement_date": "2026-03-13T00:00:00.000Z",
    "compliant_members": 5,
    "non_compliant_members": 3,
    "non_compliant": [
      { "user_id": "user_x1y2z3", "email": "alex@example.com" },
      { "user_id": "user_a4b5c6", "email": "jordan@example.com" },
      { "user_id": "user_d7e8f9", "email": "sam@example.com" }
    ]
  },
  "updated_at": "2026-03-10T10:00:00.000Z"
}

IP Allowlist

Restrict API and dashboard access to specific IP addresses or CIDR ranges. When enabled, requests from non-allowlisted IPs are rejected with a 403 status. You can apply the allowlist to API access, dashboard access, or both.

// Enable IP allowlist with CIDR ranges
await whale.security.update({
  ip_allowlist: {
    enabled: true,
    applies_to: ["api", "dashboard"],
    entries: [
      { cidr: "203.0.113.0/24", label: "Office network" },
      { cidr: "198.51.100.42/32", label: "VPN exit node" },
      { cidr: "192.0.2.0/28", label: "Warehouse" }
    ]
  }
});

// Response
{
  "object": "security_settings",
  "ip_allowlist": {
    "enabled": true,
    "applies_to": ["api", "dashboard"],
    "entries": [
      { "id": "ip_a1b2c3", "cidr": "203.0.113.0/24", "label": "Office network", "added_at": "2026-03-10T10:00:00.000Z" },
      { "id": "ip_d4e5f6", "cidr": "198.51.100.42/32", "label": "VPN exit node", "added_at": "2026-03-10T10:00:00.000Z" },
      { "id": "ip_a7b8c9", "cidr": "192.0.2.0/28", "label": "Warehouse", "added_at": "2026-03-10T10:00:00.000Z" }
    ]
  },
  "updated_at": "2026-03-10T10:00:00.000Z"
}

// Remove an entry
await whale.security.ipAllowlist.delete("ip_a7b8c9");

Session Policy

Configure session timeout, concurrent session limits, and password complexity requirements. Sessions that exceed the timeout are automatically invalidated. Sensitive operations like changing security settings or managing API keys can require re-authentication.

await whale.security.update({
  session_policy: {
    timeout_minutes: 480,           // 8 hours
    max_concurrent_sessions: 3,
    require_re_auth_for_sensitive: true
  },
  password_policy: {
    min_length: 12,
    require_uppercase: true,
    require_number: true,
    require_special: true,
    max_age_days: 90,               // force reset every 90 days
    prevent_reuse: 5                // cannot reuse last 5 passwords
  }
});

// Response
{
  "object": "security_settings",
  "session_policy": {
    "timeout_minutes": 480,
    "max_concurrent_sessions": 3,
    "require_re_auth_for_sensitive": true
  },
  "password_policy": {
    "min_length": 12,
    "require_uppercase": true,
    "require_number": true,
    "require_special": true,
    "max_age_days": 90,
    "prevent_reuse": 5
  },
  "updated_at": "2026-03-10T10:00:00.000Z"
}

API Key Rotation

Schedule automatic API key rotation to reduce the risk of compromised credentials. When rotation occurs, a new key is generated and the old key remains valid during a configurable grace period, giving your integrations time to switch over. You can also trigger an immediate rotation.

// Configure automatic rotation
await whale.security.update({
  api_key_rotation: {
    enabled: true,
    interval_days: 90,
    grace_period_hours: 48
  }
});

// Response
{
  "object": "security_settings",
  "api_key_rotation": {
    "enabled": true,
    "interval_days": 90,
    "grace_period_hours": 48,
    "last_rotation": "2026-01-01T00:00:00.000Z",
    "next_rotation": "2026-04-01T00:00:00.000Z"
  },
  "updated_at": "2026-03-10T10:00:00.000Z"
}

// Trigger immediate rotation
const rotation = await whale.security.rotateKeys({
  grace_period_hours: 24
});

// Response
{
  "object": "key_rotation",
  "new_key_prefix": "wk_live_9x8y...",
  "old_key_expires_at": "2026-03-11T10:00:00.000Z",
  "rotated_at": "2026-03-10T10:00:00.000Z",
  "rotated_keys": 2
}

API Reference