At a glance
Days until your ShipTheory API auth token expires. ShipTheory uses an OAuth bearer model with typical 365-day token windows; when the token expires, label-print, rate-shop and tracking calls fail immediately, breaking despatch end-to-end until a human re-authenticates. The card is the operational early-warning system; the alert at <14 days gives change-management cushion.
| What it counts | (token_expires_at - now) in calendar days, read live from ShipTheory’s /auth/me endpoint. Reflects the active OAuth bearer token. |
| API endpoint | GET /auth/me (ShipTheory v1 REST). Reads token_expires_at, token_id, scopes, account_id. |
| Delivery success criterion | Not applicable, this is connector health. |
| What “expired” actually breaks | Every operational call: rate-shop quotes, label generation, tracking polls, manifest collection, claims filing. Despatch stops; existing in-flight shipments continue tracking via webhook (carrier-direct). |
| Service level scope | Single token covers all connected sub-carriers and services. |
| Returns / RTO | Not applicable. |
| Currency | Not applicable. |
| Time window | RT (real-time, refreshed every 5 to 15 minutes). |
| Alert trigger | <14 days. The 14-day cushion gives non-urgent re-auth window through change-management. Below 7 days = P2; below 2 days = P1. |
| Roles | owner, operations |
Calculation
Calculated automatically from your ShipTheory data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading.Worked example
The UK home & garden merchant. Reading taken at 09:00 GMT on 12 Mar 26.| Workspace | Token issued | Token expires | Days remaining | Alert state |
|---|---|---|---|---|
| ukbrand-main | 14 Mar 25 | 14 Mar 26 | 2 | CRITICAL, <7 days |
| ukbrand-eu (DE/FR exports) | 22 Sep 25 | 22 Sep 26 | 193 | Healthy |
<14 days has been firing for 12 days. Five things to notice:
- The clock has been counting down for 363 days; nobody noticed for 351 of them. Failure mode of token-expiry: silent until catastrophic. The alert is meant to guarantee humans notice with two weeks cushion. If acknowledged but deprioritised, escalate now.
- Two days is a Friday-evening risk. If the token expires Saturday 03:00 GMT (original issue timestamp), Saturday morning despatch breaks. Monday’s despatch will face a backlog of unprocessed orders from Saturday and Sunday. Rotate today.
- The eu workspace is healthy and is the rollback path. Cross-region label printing is technically feasible from the eu workspace but requires manual override; document the path before rotating.
- Re-auth requires a human in ShipTheory’s UI. OAuth flow needs an admin to log into ShipTheory Account → API Settings, generate new token, copy bearer, paste into Vortex IQ connector. Total time <5 minutes pre-staged; coordinate with despatch downtime.
- After rotation, card resets to 365 days. Re-read 24 hours after rotation to confirm new expiry has propagated; if the card still shows <14 days, the new token did not save correctly. Record the rotation in workspace audit log.
Sibling cards merchants should reference together
Token-expiry is binary at day-level (alert fires or not), but a leading indicator for a chain of operational cards.| Card | Why pair it with Days to Token Expiry | What the combination tells you |
|---|---|---|
| API Error Rate | Lagging confirmation. Token expiry produces 401 errors. | Both red simultaneously = token already partially failing. |
| Label-Generation Success Rate | Direct downstream effect. | Drops to 0% the moment the token expires. |
| Shipments | Volume processed. | Goes to zero on token expiry. |
| Labels Printed Not Collected | Adjacent operational signal. | If labels printed but tokens expired before manifest collection, manifest gap rises. |
| Cross-connector: any other connector token-expiry card | Workspace-wide rotation hygiene. | Multiple low expiry simultaneously = rotation calendar overdue stack-wide. |
| Cross-connector: alerting / on-call rota | Ensures alert wakes someone. | If alert fires unattended, silent-failure mode returns. |
Reconciling against the vendor’s own dashboard
Where to look in ShipTheory’s own dashboard: ShipTheory Account → API Settings. The page lists the active token, issue date, expiry date, and a “Generate New Token” action. Numbers should match the card exactly (card and portal read same source). Variance >5 minutes = stale poll cycle; manual reconnect refreshes. Why our number may legitimately differ from ShipTheory’s portal:| Reason | Direction | Why |
|---|---|---|
| Connector poll lag | Ours up to 15 minutes behind | Card refreshes on poll cadence; portal reads live. Variance never exceeds 1 day. |
| Workspace selection | Either, multi-workspace | Each workspace has its own token; card reads only the connected workspace. Portal toggles per workspace. |
| Token regeneration without disconnect | Card stale until reconnect | If merchant rotates in ShipTheory portal without re-saving in Vortex IQ, card reads old (now expired) token. Most common false-alarm. |
| Card | Expected relationship | What causes legitimate divergence |
|---|---|---|
| Other shipping connectors’ token-expiry cards | Independent tokens; correlation only via rotation policy. | Quarterly stack-wide rotation produces lockstep. |
| Webhook-health monitors | Token expiry breaks API but not webhooks. | Until next outbound API call needed by connector. |