> ## Documentation Index > Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Days to Token Expiry, ShipTheory > Days to Token Expiry for ShipTheory stores. Tracked live in Vortex IQ Nerve Centre. How to read it, why it matters, and how to act on it. **Metrics type:** [Key Metrics](/nerve-centre/overview#metrics-types-explained) • **Category:** [Shipping & Courier](/nerve-centre/connectors#connectors-by-type) ## 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 | The card reads **2** days for the main UK workspace; the alert at `<14 days` has been firing for 12 days. Five things to notice: 1. **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. 2. **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. 3. **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. 4. **Re-auth requires a human in ShipTheory's UI.** OAuth flow needs an admin to log into [ShipTheory Account → API Settings](https://app.shiptheory.com/account/api), generate new token, copy bearer, paste into Vortex IQ connector. Total time \<5 minutes pre-staged; coordinate with despatch downtime. 5. **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](/nerve-centre/kpi-cards/ship-theory/api-error-rate) | Lagging confirmation. Token expiry produces 401 errors. | Both red simultaneously = token already partially failing. | | [Label-Generation Success Rate](/nerve-centre/kpi-cards/ship-theory/label-generation-success-rate) | Direct downstream effect. | Drops to 0% the moment the token expires. | | [Shipments](/nerve-centre/kpi-cards/ship-theory/shipments) | Volume processed. | Goes to zero on token expiry. | | [Labels Printed Not Collected](/nerve-centre/kpi-cards/ship-theory/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](https://app.shiptheory.com/account/api). 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. | **Cross-connector reconciliation:** | 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. | ***
Documentation cross-reference (for agencies running multi-platform stacks) Token-expiry signals are universal; auth model and rotation flow differ. * [ShippyPro Days to Token Expiry](/nerve-centre/kpi-cards/shippy-pro/days-to-token-expiry) (similar OAuth bearer) * [Sendle Days to Token Expiry](/nerve-centre/kpi-cards/sendle/days-to-token-expiry) (long-lived API key, calendared rotation)
## Known limitations / merchant FAQs **Why does ShipTheory use expiring tokens?** Security policy. ShipTheory's OAuth model rotates the bearer to limit credential-leak exposure. Standard tokens are 365-day; enterprise can request shorter (180/90). Trade-off: shorter window = more rotation work, smaller blast radius. **The token expired and despatch is broken. Recovery time?** Mechanical rotation: 5 to 10 minutes if you have ShipTheory admin access ready. Connector resumes API calls within one poll cycle (5 to 15 minutes). Backlog re-queues. Total restoration \~30 minutes; longer if you wait for an admin user. **Can I rotate proactively?** Yes, recommended. ShipTheory lets you generate a new token before the old expires; both valid simultaneously for grace period. Rotate at the 30-day mark on calendared cadence, not in firefighting mode. **Why 14-day alert specifically?** Convention across cloud-platform secret rotation. Two business weeks is enough cushion for change-management approval and rollback. Below 7 days = P2; below 2 days = P1. **Multi-workspace, separate rotation each?** Yes, each workspace has its own token; rotate independently. Build a calendar that staggers them. **What happens to in-flight shipments when token expires?** Already-printed labels continue tracking via carrier webhooks. Visible breakage is on **new** shipments: cannot rate-shop, cannot print labels, cannot file claims. **Can I automate token rotation?** Partially. ShipTheory's API supports programmatic re-issue once OAuth client is authorised. A workspace can run a quarterly script that issues new token, posts to Vortex IQ, revokes old. The OAuth handshake still needs annual re-authorisation. **My token says "never expires" but the card shows a number?** Some legacy ShipTheory accounts have non-expiring tokens. The connector falls back to a synthetic 365-day display from issue date; this is a placeholder and will not actually expire. Set the alert to "ignore" for those accounts. *** ### Tracked live in Vortex IQ Nerve Centre *Days to Token Expiry* is one of hundreds of KPI pulses Vortex IQ tracks across ShipTheory and 70+ other ecommerce connectors. Nerve Centre runs the detection layer; Vortex Mind investigates the cause when something moves; Ask Viq lets you interrogate any number in plain English. [Start for free](https://app.vortexiq.ai/login) or [book a demo](https://www.vortexiq.ai/contact-us) to see this metric running on your own data.