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 application-level approver gate. Neither inherits the invoice importer's credential.

Error Handling

Failure	Response
Endpoint permission absent	Create a replacement scoped client after approval; do not reuse a broad key.
MCP role insufficient	Route to an authorized operator or redesign the task as read-only.
Credential owner departed	Suspend and reassign or rotate before continued use.
Shared key discovered	Contain its storage and migrate workloads to distinct credentials.

flexport-enterprise-rbac