Flexport Security Basics

Overview

Flexport manages global freight logistics containing shipping manifests, customs declarations, commercial invoices, and supply chain partner data. A breach exposes trade routes, commodity values, importer/exporter identities, and customs brokerage details. Secure API credentials, webhook endpoints, and any pipeline that processes shipment tracking or purchase order data.

Prerequisites

• A named security owner, scoped secret-manager integration, access-review cadence, and approved destinations for logistics data.
• Synthetic shipment fixtures and a defined incident/revocation path.

Instructions

1. Issue least-privilege credentials per environment and integration; never put keys or secrets in source, tickets, shell history, or support bundles.
2. Verify webhook signatures using raw bodies, record opaque event identifiers only, and enforce idempotency before downstream processing.
3. Restrict access to shipping, customs, invoice, and partner data; review connected systems and remove access when the business need ends.
4. Redact diagnostics, encrypt approved exports, and rotate/revoke credentials immediately after suspected exposure.

Output

Maintain a security receipt with access owner, secret reference, approved integration, review date, rotation/revocation outcome, and redacted incident status. Never include data, documents, or keys.

Examples

Use a fictional booking event and scoped staging credential to verify that an invalid signature is rejected, a duplicate is suppressed, and revoking the credential blocks future requests. Keep only the opaque event ID and control outcome in the evidence.

API Key Management

function createFlexportClient(): { apiKey: string; baseUrl: string } {
  const apiKey = process.env.FLEXPORT_API_KEY;
  if (!apiKey) {
    throw new Error("Missing FLEXPORT_API_KEY — store in secrets manager, never in .env in production");
  }
  // Never log the key; log only a hash suffix for debugging
  console.log("Flexport client initialized (key suffix:", apiKey.slice(-4), ")");
  return { apiKey, baseUrl: "https://api.flexport.com/v2" };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyFlexportWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-hub-signature"] as string;
  const secret = process.env.FLEXPORT_WEBHOOK_SECRET!;
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const ShipmentQuerySchema = z.object({
  shipment_id: z.string().regex(/^FLEX-\d+$/),
  container_number: z.string().regex(/^[A-Z]{4}\d{7}$/).optional(),
  origin_port: z.string().length(5).optional(),
  destination_port: z.string().length(5).optional(),
  hs_code: z.string().regex(/^\d{6,10}$/).optional(),
});

function validateShipmentQuery(data: unknown) {
  return ShipmentQuerySchema.parse(data);
}

Data Protection

const FLEXPORT_SENSITIVE_FIELDS = ["customs_value", "commercial_invoice", "importer_tax_id", "broker_credentials", "hs_code"];

function redactFlexportLog(record: Record<string, unknown>): Record<string, unknown> {
  const redacted = { ...record };
  for (const field of FLEXPORT_SENSITIVE_FIELDS) {
    if (field in redacted) redacted[field] = "[REDACTED]";
  }
  return redacted;
}

Security Checklist

• API keys stored in secrets manager, .env files in .gitignore
• Webhook signatures verified on every inbound request
• Different keys for dev/staging/prod environments
• Key rotation scheduled quarterly with dual-key transition
• Git history scanned for leaked keys
• HTTPS enforced for all API calls
• Request/response logging redacts auth headers and customs values
• Least-privilege access: read-only tokens for dashboards, run tokens for operations

Error Handling

Vulnerability	Risk	Mitigation
Leaked API key	Full shipment and customs data exposure	Secrets manager + quarterly rotation
Unverified webhooks	Spoofed shipment status updates	HMAC-SHA256 signature verification
Customs data in logs	Trade compliance violation	Field-level redaction pipeline
Overly broad API scope	Access to unrelated shipment data	Role-scoped tokens per team
Unencrypted commercial invoices	Financial data breach	TLS 1.2+ in transit, AES at rest

Resources

• Flexport Webhooks
• OWASP API Security Top 10

Next Steps

See flexport-prod-checklist.