Overview
Collect the smallest evidence that can distinguish contract, permission, version, transport, and provider failures. Never archive an entire environment, log directory, request body, webhook payload, or credential file.
Prerequisites
- Incident ID, time window, surface, and failing operation
- Approved redaction rules and evidence recipient
- Known credential alias, application release, and expected Flexport version
Instructions
Step 1: Set an allowlist
Declare exact metadata fields before collection: timestamps, release SHA, surface, operation, version header, status/code/message, correlation ID, and payload digest.
Step 2: Collect configuration shape
Record variable names, endpoint hosts, feature flags, and credential aliases—not values, tokens, secret suffixes, or .env content.
Step 3: Summarize attempts
List bounded attempt timestamps and outcomes. Exclude raw request/response bodies, document data, route details, names, emails, and addresses.
Step 4: Add contract evidence
Include a minimal sanitized fixture or field-name diff only when necessary to reproduce the failure.
Step 5: Review twice
Run automated secret/sensitive-data scanning, then require a human owner to approve the exact manifest and recipient.
Step 6: Transfer and expire
Use the approved support channel, record a checksum and expiry, then delete according to incident evidence policy.
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 webhook escalation contains the receiver release SHA, event-type string, signature-header presence, body digest, status outcome, and timestamps. It contains neither the webhook body nor the secret.
Error Handling
| Failure | Response |
|---|---|
| Secret scanner fires | Stop transfer, remove the material, rotate if exposure occurred, and rescan. |
| Payload needed for reproduction | Create a synthetic minimal fixture rather than shipping production content. |
| Recipient or purpose unclear | Do not build or send the manifest. |
| Archive tool proposes broad paths | Reject it and use the explicit allowlist only. |