Flexport Integration Security Baseline
Overview
Protect four high-value boundaries: OAuth/API credentials, cached tokens, webhook secrets/raw bodies, and business mutations that can create freight or trade records.
Prerequisites
- Threat model with account, workload, and data boundaries
- Endpoint-scoped credential plan and broad-key exception register
- Secret scanning, redacted telemetry, rotation, and incident procedures
Instructions
Step 1: Minimize credentials
Prefer distinct endpoint-scoped OAuth clients. Treat API keys as broad-access exceptions and never record secret values or suffixes.
Step 2: Protect tokens
Request with the documented audience/grant, cache encrypted 24-hour JWTs, single-flight refresh, and never pass tokens through browser state or logs.
Step 3: Authenticate webhooks first
Verify raw-body HMAC-SHA256 from X-Hub-Signature-256, reject malformed/length-mismatched values, then parse and enqueue.
Step 4: Constrain egress and input
Allow documented Flexport hosts, validate schemas and sizes, preserve opaque IDs, and reject unexpected mutation intent.
Step 5: Guard mutations
Require business authorization, durable operation keys, one writer, and reconciliation before retrying bookings or record creation.
Step 6: Exercise response
Test credential revocation, webhook secret rotation, log leakage, provider outage, and rollback with metadata-only evidence.
Authentication
REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions.
Tool Discipline
Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change.
Output
- Scoped decision or implementation artifact
- Redacted operation and validation receipt
- Failure, rollback, and follow-up ownership record
Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it:
surface: rest-v3
operation: shipment-read
decision: approved
outcome: verified
evidence:
release_sha: recorded-out-of-band
provider_reference: redacted
rollback_owner: logistics-platform
Examples
A shipment reader and invoice importer use different scoped OAuth clients. A leaked client triggers revocation and replacement of only that workload, while webhook processing remains isolated behind its own secret.
Error Handling
| Failure | Response |
|---|---|
| Credential committed or logged | Revoke/rotate, contain the artifact, and repair injection/redaction. |
| Signature checked after JSON parsing | Reject the implementation and restore raw-body verification. |
| Broad key used by many workloads | Segment and migrate to scoped clients. |
| Uncertain booking retry requested | Block it until provider state is reconciled. |