OAuth2 for Shipping APIs: Authentication Done Right

Most modern carrier APIs have moved to OAuth2. FedEx switched from legacy XML auth to OAuth2 in 2024. UPS uses OAuth2 for their REST API. If you're building carrier integrations, you need solid OAuth2 implementation.

Carrier OAuth2 Flows

Token Management

The biggest mistake developers make: requesting a new token for every API call. This is wasteful and some carriers will throttle you for excessive token requests.

Cache tokens with a buffer before expiry:

• Token expires in 3600 seconds? Cache it for 3500 seconds.
• Store in Redis if you're running multiple server instances
• Store in memory if you're single-instance

When a cached token returns a 401, invalidate and re-request immediately. Don't retry with the same expired token.

Securing Token Storage

• Never store tokens in frontend code or localStorage
• Never log full tokens — log only the last 4 characters for debugging
• Always encrypt tokens at rest in your database using AES-256
• Always use HTTPS for token endpoints (carriers enforce this anyway)

E-commerce Platform OAuth2

When merchants connect their Shopify/Amazon/eBay stores, you need to handle the authorization_code flow:

Redirect merchant to platform's OAuth consent screen

Receive authorization code at your callback URL

Exchange code for access token + refresh token

Store encrypted tokens associated with the merchant's organization

Refresh tokens before they expire

Critical: If a refresh token expires (eBay's last 18 months), the merchant must re-authorize. Build a notification system that warns merchants 30 days before refresh token expiry.

Scopes and Permissions

Request the minimum scopes needed:

• For order sync: read_orders (not write_orders unless you need to update fulfillment)
• For shipping: write_fulfillments (to mark orders as shipped)
• For products: read_products (only if you need product weights/dimensions)

Over-requesting scopes reduces merchant trust during the OAuth consent screen and may trigger platform review.

Security Checklist

PKCE for authorization_code flows (prevents code interception)

State parameter to prevent CSRF attacks

Validate redirect_uri exactly matches your registered URL

Rotate client secrets every 90 days

Monitor for unusual token usage patterns (sudden spike in token requests)

See how Atoship secures carrier connections →