Store access+refresh tokens with expiry timestamps
Refresh proactively (e.g. 60s before expiry), not on 401
Serialize refreshes per user (mutex/row lock) so concurrent workers don't double-refresh
If provider rotates refresh tokens, persist the new one atomically BEFORE using it
Known gotchas
Two workers refreshing the same rotating refresh token simultaneously: the second invalidates the connection permanently (QuickBooks, Xero are notorious)
A 401 retry loop without backoff can trip provider abuse detection and revoke grants
Clock skew makes 'expires_in' arithmetic unsafe — keep a safety margin
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp