At a glance
Days remaining before the USPS Web Tools API credential the merchant uses to validate addresses, retrieve rates, and create labels stops working. USPS API credentials do not expire by default but can be revoked or rotated for security; the card tracks last-known-good state plus any explicit expiry the merchant has configured.
| What it counts | If the credential has an expiry stamp, (expires_at - now()) / 86400. If credentials have indefinite life, the card reads “Indefinite” and only flips to a countdown if a security event (suspected breach, account suspension, rotation requested) triggers a finite TTL. |
| Token type | USPS Web Tools API uses a permanent USERID assigned at registration with USPS Web Tools. Newer USPS API products (Pricing API v3, Tracking API v3) are migrating to OAuth 2.0 client-credentials with 1-year TTL. The card tracks whichever credential type the connector uses. |
| What “expired” actually breaks | Once the credential is revoked or expires, calls to USPS endpoints (AddressValidate, RateV4, eVS Label, TrackV2) return “Authentication failed” or HTTP 401. Label generation breaks; address validation breaks; rate lookups for checkout shipping calculator break (impacts conversion). |
| Detection mechanism | Vortex IQ inspects credential metadata at every call. For permanent USERID credentials, the card reads “Indefinite” until a failed-auth response triggers re-evaluation. For OAuth credentials, the card reads the token’s expires_at stamp. |
| Renewal path | For Web Tools USERID: contact USPS Web Tools Support at USPS Internet Customer Care Center to reactivate a suspended USERID. Typically 1 to 3 business days. For OAuth credentials: log into USPS Developer Portal and rotate via the project’s API Keys section. |
| Notification cadence | Card alerts at <14 days (warn) and <7 days (critical) for OAuth credentials. For USERID credentials, alerts trigger only on failed-auth observed events. Vortex IQ also sends in-app banners and email at 14, 7, 3, and 1 day. |
| Time window | RT (real-time, refreshed hourly) |
| Alert trigger | <14 days (warn) / <7 days (critical) |
| Roles | owner, operations |
Calculation
Calculated automatically from your USPS data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading.Worked example
A US DTC merchant connected USPS Web Tools on 04 Mar 25. Reading taken on 12 Mar 26.| Date | Days to expiry | Card state | What happened |
|---|---|---|---|
| 04 Mar 25 | Indefinite | green | Initial connection. Web Tools USERID issued. |
| 22 Aug 25 | Indefinite | green | Migrated to USPS Tracking API v3 (OAuth). New TTL 365 days. Card now shows countdown. |
| 22 Feb 26 | 28 | green | Approaching warn threshold. |
| 06 Mar 26 | 16 | green | First Vortex IQ pre-warn email. |
| 08 Mar 26 | 14 | amber | Warn alert tripped. |
| 12 Mar 26 | 10 | amber | Reading at this example. |
- Rotate the OAuth credential this week. Open USPS Developer Portal, regenerate the client_id and client_secret pair for the project, paste into Vortex IQ Settings → Connectors → USPS. Total downtime: under 5 minutes if done proactively.
- Schedule annual rotation reminder. USPS OAuth credentials default to 365 days. Add a calendar reminder for 11 months from now.
- Watch for legacy USERID also. If the connector is on USPS Web Tools v3 OAuth for tracking but still uses the older Web Tools USERID for AddressValidate, both need to be active. Migration to v3 across all endpoints is ongoing through 2026.
Sibling cards merchants should reference together
| Card | Why pair it with Days to Token Expiry | What the combination tells you |
|---|---|---|
| API Error Rate | Captures partial failures between rotation events. | Expiry counts down deterministically; error-rate spikes flag transient USPS Web Tools outages or rate-limit overruns. |
| Label Generation Success Rate | Downstream workload that breaks on auth failure. | Sudden drop in label success with green expiry = something else broke (rate limits, payload errors); drop with red expiry = auth. |
| Shipments Total | Volume context. | Volume falling to zero with expiry at zero confirms expiry is the cause. |
Cross-connector: fedex.fed_auth_token_expiry_days | Multi-carrier connector-health view. | If both expire close together, plan rotation jointly. |
Cross-connector: shopify.unfulfilled_orders | Downstream impact. | Unfulfilled-order spike co-occurring with expiry-at-zero is the unmistakable expiry-caused outage signature. |
Reconciling against the vendor’s own dashboard
Where to look in USPS’s own dashboard: USPS Web Tools (legacy USERID): no expiry view; USERIDs are permanent unless revoked. Check status by attempting an API call. USPS Developer Portal (OAuth, v3 APIs): My Projects → [Project] → API Keys shows credential creation date and TTL. Why our number may legitimately differ from USPS’s portal:| Reason | Direction | Why |
|---|---|---|
| Credential type | Either | Legacy USERID has indefinite life; OAuth has 365-day TTL. The card reflects the connector’s active credential type. |
| Manual revocation | Card may show stale | If USPS Web Tools admin revokes a USERID without notification, the card continues to read “Indefinite” until the next failed-auth event. |
| Migration state | Either | Merchants migrating from Web Tools v1 to v3 OAuth may have both credential types active; the card reads whichever is configured. |
| Card | Expected relationship | What causes legitimate divergence |
|---|---|---|
fedex.fed_auth_token_expiry_days | Peer carrier connector. | Different lifetime conventions; FedEx defaults to 365-day OAuth, USPS legacy defaults to indefinite. |
easypost.eas_auth_token_expiry_days | Aggregator alternative. | EasyPost issues a single permanent API key but masks the underlying USPS credential lifecycle. |