Fork-Safe Flexport Contract CI

Overview

The required CI lane must run without Flexport secrets and remain safe for forks. Live verification belongs in a protected, non-fork, read-only lane with explicit environment approval.

Prerequisites

• Sanitized REST, MCP, OAuth-error, and webhook fixtures
• CI permissions model and fork-event policy
• Optional test credential approved through Flexport/account ownership

Instructions

Step 1: Build the required lane

Validate schemas, tolerant additive fields, pagination, error classification, webhook raw-body signatures, and mutation guards entirely from fixtures.

Step 2: Test secret absence

Assert default tests cannot resolve Flexport credentials or reach live mutation adapters.

Step 3: Protect fork execution

Never expose repository/environment secrets to untrusted pull-request code; keep required fork checks credential-free.

Step 4: Define an optional live lane

Run only from trusted refs after environment approval, inject a scoped credential, and permit one documented read-only proof.

Step 5: Block mutations

Enforce an adapter-level CI policy that rejects booking, document, invoice, or purchase-order writes even when a credential exists.

Step 6: Publish receipts

Attach test counts, fixture/source dates, release SHA, and redacted live outcome; never upload tokens or provider payloads.

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

Every pull request tests v3 shipment envelopes, MCP cursor handling, malformed webhook signatures, and ambiguous booking guards. A protected main-branch job may perform one shipment list read with a test credentia…

Flexport Failure Classification

Overview

Do not convert every failure into a retry. First identify the surface and operation class, then distinguish authentication, authorization, validation, provider availability, and ambiguous mutation outcomes.

Prerequisites

• Redacted surface and operation name
• HTTP status or JSON-RPC error plus documented provider code/message
• Knowledge of whether the failed operation could mutate freight or trade records

Instructions

Step 1: Identify the surface

Label OAuth token, REST v3, MCP JSON-RPC, or webhook delivery; each has different failure semantics.

Step 2: Protect evidence

Capture timestamp, credential alias, version header, operation digest, status/code/message, and provider correlation metadata without payloads or secrets.

Step 3: Classify deterministically

Separate 401 authentication, 403 permission/scope, 404 resource or route, 400/422 request validation, throttling evidence, and 5xx/transport uncertainty.

Step 4: Choose retry eligibility

Retry only transient, idempotent work with bounded backoff. Never retry a create or booking until its prior outcome is reconciled.

Step 5: Correct the owner

Route credential issues to credential owners, schema issues to integration owners, business validation to data owners, and provider incidents to support.

Step 6: Close with a proof

Record the corrected contract or recovered result and add a regression fixture when the defect was local.

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 document upload returns 422 with a provider message. The operator preserves the code/message, fixes the source doc…

Approval-Gated Flexport Rate to Booking

Overview

Separate discovery from commitment. MCP rate tools can search, evaluate, request, and book; a booking must never be inferred from a search result or performed before a named approver accepts the final normalized terms.

Prerequisites

• Validated origin, destination, cargo, dates, mode, and incoterm
• Authenticated connection to https://mcp.flexport.com/mcp
• Named approver, spend boundary, and duplicate-prevention store

Instructions

Step 1: Normalize the lane

Resolve addresses, company entities, ports, addresses, and commodity inputs with read-only network tools. Preserve opaque Flexport identifiers.

Step 2: Search without commitment

Call rates_search_instant_price with approved inputs and store the search/result identifiers plus a redacted input digest.

Step 3: Evaluate the candidate

Use rates_evaluate_total_price_from_instant_price_search for the selected result. Present currency, charge breakdown, timing, assumptions, and expiry exactly as returned.

Step 4: Choose the branch

If instant booking is unavailable, use rates_request_rate and reconcile the quote request. Do not substitute rates_book_without_rate unless that supplier flow was explicitly approved.

Step 5: Require human approval

Bind the approver, exact evaluated result, cargo digest, and approval expiry. Re-evaluate when any material input or provider term changes.

Step 6: Book once and reconcile

Persist an operation key before rates_instant_book; store the returned booking reference and reconcile ambiguous outcomes before any retry.

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
  p…

Flexport Trade Document Workflow

Overview

Treat structured trade records and uploaded files as separate governed operations. Validate referenced network entities first, apply only documented create/update behavior, and never assume an uploaded document can be updated in place.

Prerequisites

• Approved source record and data owner
• Resolved Flexport entity, location, shipment, and product references
• Document malware scan, MIME policy, and retention decision

Instructions

Step 1: Select the resource

Choose purchase order, commercial invoice, or document from the business outcome; do not overload one endpoint with another resource's fields.

Step 2: Resolve references

Verify network entity, location, shipment, and product identifiers with read-only lookups before mutation.

Step 3: Validate permissions

Confirm the OAuth credential includes the required endpoint resource. Commercial invoice create/update also requires Flexport-side enablement and permission.

Step 4: Submit once

Persist an operation digest, then use the documented endpoint: /purchase_orders, /commercial_invoices, or /documents. Base64 document content must remain within the documented 10 MB pre-encoding limit.

Step 5: Reconcile the result

Store opaque returned IDs and retrieve the resource. For documents, replace through an approved new upload rather than inventing an update call.

Step 6: Record lineage

Link the Flexport resource to the approved source revision, actor, version header, and redacted outcome.

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 validated commercia…

Flexport Request-Volume and Freshness Tuning

Overview

Optimize volume and latency against business freshness, not a fabricated per-request bill. Prefer event-driven invalidation plus bounded reconciliation and measured page/expansion choices.

Prerequisites

• Baseline request counts by operation and outcome
• Business-approved freshness and recovery windows
• Metrics for pages read, expansions, cache hits, and reconciliation lag

Instructions

Step 1: Name the outcome

Tie each request to shipment tracking, trade document ingestion, invoice reconciliation, or booking—not generic synchronization.

Step 2: Set freshness classes

Define active-shipment, completed-shipment, invoice, and reference-data windows from operational need; do not hard-code invented provider change rates.

Step 3: Use events as hints

Let authenticated webhooks trigger targeted reads, then run bounded periodic reconciliation for missed deliveries.

Step 4: Trim reads

Stop pagination at the required window, request only supported expansions, and avoid expansion on invoice index calls where Flexport recommends against it.

Step 5: Cache safely

Cache read-only reference results under an explicit TTL and invalidate on evidence; never cache credentials, authorization decisions, or mutable booking approval.

Step 6: Prove the change

Compare request count, stale-result rate, reconciliation time, and provider errors before and after; roll back if correctness worsens.

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 dashboard refreshes active records from verified events and a bounded reconciler, while completed shipm…

Flexport Logistics Data Minimization

Overview

Flexport payloads can contain commercial, personal, customs, financial, and document content. This skill does not invent universal GDPR, CCPA, ITAR, or retention rules; it makes the accountable owner and policy explicit.

Prerequisites

• Documented purpose and accountable data owner
• Field-level source-to-destination map
• Approved classification, residency, access, retention, and deletion policy

Instructions

Step 1: Inventory exact fields

Map only fields needed for the approved outcome, including identifiers embedded in routes, parties, documents, invoices, customs, tags, or MCP tracking output.

Step 2: Classify with policy

Apply the organization's authoritative classification and legal guidance. Do not infer a regime from an HS code, endpoint, country, or shipment mode.

Step 3: Minimize collection

Prefer opaque resource IDs and derived operational state over raw documents, addresses, names, emails, entry numbers, or charge details.

Step 4: Protect transport and storage

Use approved encrypted channels and stores, workload-scoped credentials, tenant boundaries, and access logging.

Step 5: Control outputs

Redact logs, metrics, prompts, tickets, debug bundles, and analytics. Never include document bodies, tokens, or full route/party payloads by default.

Step 6: Enforce lifecycle

Attach retention/deletion rules to the approved data class, test deletion and backup behavior, and record exceptions with owner and expiry.

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 delay alert stores a shipment's opaque Flexport ID, milestone c…

Redacted Flexport Diagnostic Manifest

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 o…

Flexport Integration Deployment Canary

Overview

Keep deployment mechanics provider-neutral and Flexport validation surface-specific. A safe release proves secret injection, read-only access, version handling, webhook raw-body verification, and mutation gates before traffic expands.

Prerequisites

• Immutable release artifact and reviewed configuration diff
• Secret references supplied by the deployment platform, not command-line values
• Read-only canary and tested rollback procedure

Instructions

Step 1: Classify the change

Label REST schema/version, OAuth credential, MCP tool/session, webhook receiver, or business-policy change and name its rollback unit.

Step 2: Validate offline

Run contract fixtures for documented success, additive fields, auth errors, webhook signatures, and ambiguous mutations.

Step 3: Deploy dark

Start the release with mutations disabled and no automatic booking, document creation, or record update.

Step 4: Run a read-only canary

Reuse a cached token and perform one approved shipment read or MCP tracking call. For receivers, send a signed synthetic fixture through the exact raw-body path.

Step 5: Expand gradually

Increase traffic by a reversible cohort while monitoring auth, permission, parsing, queue, duplicate, and reconciliation outcomes.

Step 6: Rollback on invariant breach

Restore the prior artifact/configuration together, preserve redacted evidence, and reconcile any ambiguous in-flight mutation.

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 receiver release first validates a synthetic X-Hub-Signature-256 request, then receives a smal…

Flexport Permission-Aware Access Broker

Overview

Flexport has two access concepts that must not be conflated: OAuth clients select endpoint resources, while MCP tools document allowed account roles. API keys are broad across endpoints and should not be described as selectively scoped.

Prerequisites

• Workload-to-outcome inventory and accountable owners
• Current REST endpoint resource and MCP tool permission documentation
• Credential registry with environment and rotation metadata

Instructions

Step 1: Map business outcomes

List reads, document changes, invoice work, booking commitments, and MCP tools by workload.

Step 2: Assign separate credentials

Create one OAuth client per system and select only required endpoint resources. Create a replacement if new resources are later needed.

Step 3: Map MCP roles

For each MCP tool, record the documented allowed roles and verify the connected user has one; do not infer permission from a REST credential.

Step 4: Control broad keys

Inventory API keys as exceptions, document their all-endpoint blast radius, restrict storage, and plan replacement where OAuth fits.

Step 5: Enforce application policy

Require business authorization above provider permission, especially for bookings, trade records, and sensitive shipment/customs data.

Step 6: Review with evidence

Quarterly or event-driven reviews compare active workloads, credentials, tool use, and owners; revoke orphaned access promptly.

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 tracking service gets shipment-only OAuth resources, while an MCP booking assistant runs for a Member with an …

Read-Only Flexport v3 Proof

Overview

Establish connectivity without creating freight, documents, or bookings. Pin the intended API version, accept documented response wrappers, and preserve only a redacted proof.

Prerequisites

• Approved read-only credential and credential alias
• Known account API version or explicit Flexport-Version choice
• A test policy that permits either one shipment reference or an empty list

Instructions

Step 1: Define the proof

Set the expected account, endpoint, version, and allowed evidence before making a call.

Step 2: Acquire authentication

Reuse a cached OAuth client-credentials token, or use an explicitly approved API key. Keep the credential out of command text and logs.

Step 3: Request shipments

Send GET https://api.flexport.com/shipments with Bearer authorization, JSON acceptance, and Flexport-Version: 3 when an explicit v3 override is intended.

Step 4: Parse defensively

Read the documented response envelope and pagination links without assuming invented ID prefixes, undocumented nested records, or a fixed set of additive fields.

Step 5: Validate tenant safety

Confirm the response belongs to the intended account and emit only count, HTTP status, selected version, and a hashed operation identifier.

Step 6: Fail closed

Do not progress from a successful read to document creation, booking, or mutation. Make the next action a separate approved workflow.

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 deployment probe requests the first shipment page with a cached OAuth token, confirms HTTP 200 and the intende…

Flexport Delivery-Gap Incident Runbook

Overview

Preserve freight correctness first. Freeze uncertain mutations, separate provider delivery from local processing, and reconstruct affected state with documented resource/event reads.

Prerequisites

• Incident owner, severity, start time, and affected tenant/workflow
• Last known good release and configuration
• Bounded reconciliation query and business owners for disputed state

Instructions

Step 1: Contain

Disable automatic bookings and affected writes. Keep authenticated webhook acceptance only if durable enqueue and deduplication remain correct.

Step 2: Bound the window

Identify first/last bad receipt by surface, operation, release, credential alias, and version without examining broad sensitive payloads.

Step 3: Split failure domains

Test OAuth, REST read, MCP connection, webhook ingress, queue processing, and downstream state independently.

Step 4: Reconcile read-only

Use /events or affected resource reads to compare provider state with durable local operation keys. Do not assume Flexport exposes a webhook replay endpoint.

Step 5: Repair deterministically

Reprocess authenticated durable events or apply approved state corrections exactly once; reconcile uncertain creates/bookings before retry.

Step 6: Recover and learn

Restore traffic by cohort, verify the full incident window, rotate exposed credentials if needed, and add a sanitized regression fixture.

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 receiver deployment parsed bodies before signature validation and dropped events. The team restores the prior relea…

Flexport Credential and Token Boundary

Overview

Prefer a distinct endpoint-scoped OAuth client for each workload. Treat broad API keys as an explicit exception, and budget token acquisition because client-credential tokens last 24 hours while token requests are limited to 10 per day.

Prerequisites

• Named workload owner and exact endpoint inventory
• Flexport administrator access to API Credentials
• Secret store, redacted audit sink, and rotation procedure

Instructions

Step 1: Choose the credential type

Use OAuth client credentials for new integrations so endpoint resources can be selected. Accept an API key only after documenting why its broad access is necessary.

Step 2: Create one credential per system

Separate production, non-production, and independent workloads. Flexport does not let operators add endpoints to an existing credential, so create a replacement when scope must expand.

Step 3: Request a token once

POST to /oauth/token with client_id, client_secret, audience https://api.flexport.com, and grant type client_credentials. Never expose the secret in a browser, shell history, or receipt.

Step 4: Cache by credential

Store the JWT and expiry in a concurrency-safe cache. Refresh before expiry with jitter and a single-flight lock; do not spend the 10-request daily token budget per business request.

Step 5: Prove least privilege

Run one approved read against every required endpoint and one negative test against an endpoint outside the credential resource set.

Step 6: Rotate without ambiguity

Create and validate a replacement, switch one workload, observe it, then revoke the old credential. Record only credential aliases, timestamps, and outcome.

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: …

Flexport Contract-Fixture Development Loop

Overview

Most development should run without credentials. Model official v3, MCP, and webhook shapes as fixtures, then use a separately approved read-only live smoke test only for gaps fixtures cannot prove.

Prerequisites

• Current first-party schema pages and snapshot date
• Sanitized success, pagination, additive-field, and error fixtures
• Separate local secret injection and no-production-data rule

Instructions

Step 1: Choose one contract

Name the exact REST endpoint, MCP tool, or webhook event and expected business outcome.

Step 2: Capture shape, not data

Build synthetic fixtures from documented field names/types. Replace all identifiers, routes, parties, financials, and document content.

Step 3: Test invariants

Cover required fields, unknown additive fields, opaque cursors/links, status/code/message errors, and missing authorization.

Step 4: Exercise raw webhooks

Sign exact synthetic bytes with a test secret and test malformed, wrong-length, duplicate, and valid SHA-256 signatures before parsing.

Step 5: Gate live checks

If needed, use an approved credential for one read-only operation. Never create bookings, documents, purchase orders, or invoices from the local loop.

Step 6: Promote the receipt

Commit fixtures and assertions, not tokens or live payloads; record schema source and review date.

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 developer implements browse_shipments pagination using synthetic end_cursor fixtures, adds an unknown field to prove tolerant parsing, and keeps the real MCP connecti…

Controlled Flexport Integration Migration

Overview

Migration is a sequence of read-only comparison, explicit field mapping, shadow evaluation, and one controlled write owner. Never dual-book freight or dual-create trade records merely to compare systems.

Prerequisites

• Endpoint/tool inventory with read/write classification
• Captured account default version and any Flexport-Version overrides
• Business-key mapping, rollback plan, and reconciliation owner

Instructions

Step 1: Inventory reality

Trace every legacy path, version header, response assumption, event name, expansion, credential, and mutation.

Step 2: Map to documented targets

Choose current v3 REST endpoints or MCP tools by outcome. Record unsupported fields/operations rather than guessing equivalents.

Step 3: Build tolerant readers

Accept documented envelopes and additive fields, preserve opaque identifiers, and add sanitized fixtures for old/new differences.

Step 4: Shadow reads only

Compare current and target read paths over an approved sample. Normalize only business facts and investigate discrepancies.

Step 5: Cut over one writer

Freeze the legacy mutation queue, reconcile in-flight operations, switch one authoritative writer, and retain a rapid rollback that cannot produce concurrent writes.

Step 6: Verify and retire

Reconcile provider resources, events, and local operation keys across the cutover window before removing old credentials/code.

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 v2-era shipment reader moves to v3 with an explicit version override and tolerant fields. Its booking path rema…

Flexport Environment and Credential Isolation

Overview

Flexport documents the same API base rather than arbitrary environment URLs. Isolation comes from accounts/credentials, receiver URLs, data policy, and mutation gates; a test credential may require coordination with the account executive.

Prerequisites

• Environment/account matrix and data classification
• Distinct credential aliases and secret-store namespaces
• Separate webhook URLs, queues, databases, and mutation policy

Instructions

Step 1: Define each boundary

For every environment record account identity, credential type, endpoint resources, version behavior, receiver, data class, and permitted operations.

Step 2: Issue distinct credentials

Never share client IDs, client secrets, API keys, cached tokens, or MCP sessions across environments.

Step 3: Keep canonical hosts

Use documented Flexport API/MCP hosts. Do not invent staging subdomains or infer an environment from a credential prefix.

Step 4: Control test access

Request any Flexport test credential through the documented account-executive route and keep local/default tests fixture-only.

Step 5: Gate promotion

Promote immutable artifacts while supplying environment-specific secret references and config. Production mutations remain disabled until canary approval.

Step 6: Prove non-crossing

Test that each environment rejects another's credential alias, callback destination, queue, and data-store identity.

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

Staging and production run the same artifact against documented hosts, but use different credential …

Identifier-Safe Flexport Observability

Overview

Observe operations and reconciliation, not shipment contents. Build low-cardinality telemetry around surface, operation class, outcome, version, and queue health while keeping identifiers and payloads out.

Prerequisites

• Approved metric labels and redaction rules
• Operation taxonomy across OAuth, REST, MCP, webhook, and local processing
• Business-defined service objectives and incident ownership

Instructions

Step 1: Define safe dimensions

Use environment, surface, operation class, status family, error class, version selection, and release. Exclude URLs with IDs, names, emails, routes, tags, documents, tokens, and raw messages.

Step 2: Measure auth health

Track cache hit, refresh success, token-request count, and credential alias as a controlled internal dimension; never log tokens or secret fragments.

Step 3: Measure reads and mutations separately

Record latency, attempts, pages, queue age, reconciliation lag, and ambiguous outcomes by operation class.

Step 4: Measure webhooks in stages

Distinguish received, signature-valid, durably queued, deduplicated, processed, and reconciled counts.

Step 5: Alert on objectives

Derive thresholds from approved freshness, queue, and error objectives—not arbitrary fixed seconds or undocumented rate headers.

Step 6: Audit telemetry

Sample schemas and label cardinality for sensitive leakage and regressions before expanding collection.

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 dashboard shows surface=mcp, operation=shipment-read, outcome, latency, and reconciliati…

Measured Flexport Pagination and Concurrency

Overview

Performance tuning must preserve correctness, account boundaries, and provider stability. Change one pagination, expansion, cache, or concurrency control at a time and validate full reconciliation.

Prerequisites

• Baseline latency, pages, payload size, errors, and business freshness
• Documented pagination model for the selected REST endpoint or MCP tool
• Bounded worker pool and reversible configuration

Instructions

Step 1: Select one bottleneck

Name the operation, surface, dataset window, and business objective. Exclude token acquisition from request concurrency by using a shared cache.

Step 2: Use native pagination

Follow REST response links where documented; for MCP browse_shipments, advance end_cursor while has_next_page is true and keep first within 1–100.

Step 3: Control expansions

Avoid expansion on freight-invoice index calls as recommended; fetch detail only for records that need it.

Step 4: Increase cautiously

Raise one page-size or worker limit for read-only work, measure latency/error/backlog effects, and stop on provider or correctness degradation.

Step 5: Protect mutations

Keep bookings and trade-record writes serialized by business key and outside bulk read tuning.

Step 6: Reconcile the result

Compare counts and terminal cursors/links over the same bounded window, then document the chosen control and rollback.

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-risk scanner tests MCP page sizes of 10 and 50 on the same approved window, verifies identic…

Flexport Production Readiness Gate

Overview

A checklist item passes only with a receipt tied to the immutable release and configuration. Read access, bookings, trade records, and webhook processing have different risk boundaries and must be approved separately.

Prerequisites

• Immutable release SHA and environment manifest
• Named technical, security/data, and business approvers
• Read-only canary, reconciliation plan, incident owner, and rollback

Instructions

Step 1: Gate identity and auth

Verify account, credential alias/type, endpoint resources, token caching, secret injection, revocation, and MCP role permissions where used.

Step 2: Gate contracts

Confirm v3/account version behavior, tolerant additive-field parsing, documented endpoints/tools, error classification, and pagination.

Step 3: Gate data

Approve field minimization, destinations, telemetry redaction, retention/deletion, and tenant boundaries.

Step 4: Gate mutations

Require durable operation keys, business approval for bookings/writes, ambiguous-outcome reconciliation, and one authoritative writer.

Step 5: Gate webhooks

Prove raw-body X-Hub-Signature-256 validation, durable enqueue before 200, deduplication, event allowlist, and gap reconciliation.

Step 6: Gate launch and rollback

Run a read-only canary, expand by cohort, test rollback, and attach all receipts to the release decision.

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

The launch record enables shipment reads and signed webhook ingestion but leaves booking disabled because its human approval and ambiguous-outcome reconciliation evidence is …

Evidence-Driven Flexport Quota Control

Overview

Build controls from documented endpoint constraints and observed responses, not a fictional universal requests-per-minute number. The clearest fixed budget is OAuth token issuance: at most 10 token requests per day per documented credential flow.

Prerequisites

• Inventory by OAuth, REST endpoint, and MCP tool
• Shared token cache and per-workload queues
• Observed statuses, provider messages, and latency without sensitive payloads

Instructions

Step 1: Separate budgets

Track token acquisition, read traffic, mutations, webhook processing, and MCP tool calls independently.

Step 2: Eliminate token churn

Reuse each 24-hour OAuth JWT through a shared cache and single-flight refresh so business concurrency does not consume the 10/day token-request budget.

Step 3: Honor explicit evidence

Apply endpoint-specific documented limits and provider retry signals when present. Do not assume rate-limit headers or Retry-After exist universally.

Step 4: Shape reads

Use documented page sizes/cursors or links, avoid expensive expansions on index calls, and stop pagination when the business window is satisfied.

Step 5: Serialize mutations

Queue bookings and record creation by business key, cap attempts, and reconcile ambiguous outcomes before retry.

Step 6: Tune from receipts

Change concurrency only from measured latency/error evidence and preserve the before/after decision.

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

An importer reads freight invoices from /invoices in pages of 10 as recommended for performance, caches its…

Flexport REST, MCP, and Webhook Architecture

Overview

Use three explicit provider planes: REST v3 for resource operations, MCP Streamable HTTP JSON-RPC for permissioned assistant tools, and signed webhooks for notifications. Join them only through durable application policy and reconciliation.

Prerequisites

• Capability inventory split into reads, mutations, events, and assistant tools
• Identity, account, environment, and data-flow boundaries
• Business approval, operation ledger, queue, and recovery requirements

Instructions

Step 1: Draw provider surfaces

Show api.flexport.com, mcp.flexport.com/mcp, and public HTTPS webhook ingress as distinct external nodes.

Step 2: Place credential boundaries

Use endpoint-scoped OAuth clients per REST workload, authenticated MCP sessions with documented tool roles, and a separate webhook secret.

Step 3: Separate control and data

Put business approval and policy before booking/trade mutations; keep payload handling in minimized data services.

Step 4: Add durable state

Persist operation keys, provider references, event dedupe state, cursor/link checkpoints, and redacted outcomes.

Step 5: Add reconciliation

Connect events and uncertain outcomes to authorized REST/resource reads. Never make webhook delivery the sole source of truth.

Step 6: Prove failure paths

Model token-cache failure, permission denial, additive schema change, duplicate/missing event, ambiguous mutation, and rollback.

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 booking assistant queries rates through MCP, sends an exact candidate to an approval …

Flexport Dual-Surface Client Contracts

Overview

REST resources and MCP tools are two distinct public surfaces. Keep separate transports, authentication/session handling, error models, and pagination adapters behind business-level interfaces.

Prerequisites

• Inventory of required REST endpoints and MCP tools
• Pinned account/version behavior and schema snapshot date
• Runtime validation, redaction, timeout, and test-fixture strategy

Instructions

Step 1: Define business ports

Express outcomes such as readShipment, browseRisk, or evaluateRate; keep HTTP paths and MCP JSON-RPC details behind adapters.

Step 2: Build the REST adapter

Use base https://api.flexport.com, Bearer authentication, optional Flexport-Version, documented envelopes, status/code/message errors, and link-style pagination where documented.

Step 3: Build the MCP adapter

Use Streamable HTTP JSON-RPC at POST https://mcp.flexport.com/mcp. Treat the per-tool paths shown in reference pages as synthetic documentation, not literal REST routes.

Step 4: Validate at runtime

Accept documented additive fields, preserve opaque identifiers/cursors, and reject missing required fields without guessing replacements.

Step 5: Normalize evidence, not schemas

Return a stable application result and surface provider metadata separately; do not force REST and MCP payloads into one lossy provider model.

Step 6: Contract-test both surfaces

Replay sanitized official-shape fixtures for success, pagination, permission errors, additive fields, and ambiguous transport failure.

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
rollb…

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…

Flexport Version-Tolerant Upgrade

Overview

Flexport supports account-default version selection plus per-request Flexport-Version overrides. Backward-compatible additions can include attributes, resources, optional parameters, enum values, and event types, so readers and routers must be additive-tolerant.

Prerequisites

• Current account default and every application override
• Endpoint/event inventory with sanitized fixtures
• Target-version diff, owner approvals, canary, and rollback

Instructions

Step 1: Discover effective versions

Record the account default and explicit header behavior for every client; do not assume a hardcoded v2 path determines the contract.

Step 2: Classify changes

Separate breaking target-version differences from compatible additions that may appear without an account-version switch.

Step 3: Harden readers

Ignore or preserve unknown optional fields, route unknown enum/event values safely, and fail only when a required invariant is absent.

Step 4: Test with overrides

Exercise approved read-only calls using the target Flexport-Version header while production remains on its current default.

Step 5: Canary one cohort

Deploy tolerant code first, switch a bounded read cohort, compare business outcomes, then enable mutations only after reconciliation passes.

Step 6: Change default last

Coordinate account-default changes after all clients are ready, retain explicit rollback overrides, and verify events plus in-flight operations.

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 parser learns to preserve unknown shipment attributes and qua…

Flexport Webhook Integrity and Reconciliation

Overview

Authenticate before parsing. Flexport documents both SHA-1 and SHA-256 signatures, with SHA-256 recommended in X-Hub-Signature-256; compare against the raw UTF-8 body and treat webhook delivery as a notification that may require API reconciliation.

Prerequisites

• Unique receiver URL and high-entropy webhook secret
• Framework support for raw request bytes before JSON parsing
• Allowlisted slash/hash event types and idempotency store

Instructions

Step 1: Register deliberately

Configure the callback and secret in Flexport account Settings. Record the intended event types and owner.

Step 2: Capture raw bytes

Read the exact request body before middleware transforms encoding or JSON layout.

Step 3: Verify SHA-256

Compute HMAC-SHA256 with the stored secret, parse X-Hub-Signature-256, reject malformed or unequal-length inputs, and use constant-time comparison.

Step 4: Acknowledge quickly

After authentication and durable enqueue, return HTTP 200 promptly. Keep business processing out of the request path.

Step 5: Deduplicate and route

Use provider event identity when present or a stable payload digest. Allow only documented names such as /shipment#created or /purchase_order#updated.

Step 6: Reconcile gaps

Use authorized REST /events or resource reads when evidence indicates a delivery gap; do not invent a webhook replay endpoint or retry schedule.

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

The receiver verifies X-Hub-Signature-256 over untouched bytes…