Flexport Install & Auth Skill

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

# .env (NEVER commit — add to .gitignore)
FLEXPORT_API_KEY=your_api_key_here

# OR for OAuth credentials flow:
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

// src/flexport/client.ts
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.

Agent Skills: Flexport Install & Auth

Install this agent skill to your local

Skill Files