Flexport Install & Auth
Overview
Configure Flexport API authentication for logistics and supply chain integration. Flexport offers two auth methods: API Keys (simple bearer tokens that never expire) and API Credentials (client ID/secret pairs that issue JWTs valid for 24 hours). The v2 REST API base URL is https://api.flexport.com and speaks JSON.
Prerequisites
- Flexport account at flexport.com
- API key or credentials from Flexport Portal > Settings > Developer > API Credentials
- Node.js 18+ or Python 3.9+
Instructions
Step 1: Obtain API Credentials
Navigate to Flexport Portal > Settings > Developer. Two options:
| Auth Method | Format | Lifetime | Use Case |
|---|
| API Key | Bearer token string | Permanent | Simple integrations, scripts |
| API Credentials | Client ID + Secret | JWT, 24h | Production apps, rotating tokens |
Step 2: Configure Environment Variables
FLEXPORT_API_KEY=your_api_key_here
FLEXPORT_CLIENT_ID=your_client_id
FLEXPORT_CLIENT_SECRET=your_client_secret
FLEXPORT_API_URL=https://api.flexport.com
Step 3: Authenticate with API Key
const FLEXPORT_BASE = 'https://api.flexport.com';
async function flexportRequest(path: string, options: RequestInit = {}) {
const res = await fetch(`${FLEXPORT_BASE}${path}`, {
...options,
headers: {
'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
'Content-Type': 'application/json',
'Flexport-Version': '2',
...options.headers,
},
});
if (!res.ok) throw new Error(`Flexport ${res.status}: ${await res.text()}`);
return res.json();
}
Step 4: OAuth Credentials Flow (Production)
let tokenCache: { token: string; expiresAt: number } | null = null;
async function getAccessToken(): Promise<string> {
if (tokenCache && Date.now() < tokenCache.expiresAt) return tokenCache.token;
const res = await fetch('https://api.flexport.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
client_id: process.env.FLEXPORT_CLIENT_ID,
client_secret: process.env.FLEXPORT_CLIENT_SECRET,
grant_type: 'client_credentials',
}),
});
const { access_token, expires_in } = await res.json();
tokenCache = { token: access_token, expiresAt: Date.now() + (expires_in - 60) * 1000 };
return access_token;
}
Step 5: Verify Connection
async function verifyFlexport() {
const data = await flexportRequest('/shipments?per=1&page=1');
console.log(`Connected. Shipments found: ${data.data?.records?.length ?? 0}`);
}
await verifyFlexport();
Error Handling
| Error | Code | Cause | Solution |
|---|
Unauthorized | 401 | Invalid or expired key | Regenerate in Portal > Developer |
Forbidden | 403 | Insufficient scope | Check key permissions |
Token expired | 401 | JWT past 24h | Re-fetch via client credentials |
Rate limit exceeded | 429 | Too many requests | Exponential backoff |
Examples
Python Client
import os, requests
class FlexportClient:
BASE = 'https://api.flexport.com'
def __init__(self):
self.session = requests.Session()
self.session.headers.update({
'Authorization': f'Bearer {os.environ["FLEXPORT_API_KEY"]}',
'Content-Type': 'application/json',
'Flexport-Version': '2',
})
def get(self, path, params=None):
r = self.session.get(f'{self.BASE}{path}', params=params)
r.raise_for_status()
return r.json()
cURL Verification
curl -s -H "Authorization: Bearer $FLEXPORT_API_KEY" \
-H "Flexport-Version: 2" \
https://api.flexport.com/shipments?per=1 | jq '.data.records | length'
Resources
Next Steps
After successful auth, proceed to flexport-hello-world for your first shipment query.
