> ## 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, EasyPost > Days to Token Expiry for EasyPost 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:** [Operational Health](/nerve-centre/connectors#connectors-by-type) ## At a glance > Countdown, in days, until the EasyPost credential your despatch operation relies on to buy labels and pull tracking stops working. EasyPost itself issues a long-lived API key rather than a short OAuth token, so this card is the early-warning clock for any credential on the account that does expire: an API key with a self-imposed rotation cut-off, an underlying carrier account's auth grant (for example a directly-linked UPS, FedEx or DHL account), or a webhook signing secret on a deprecation schedule. When the soonest one reaches zero, label purchase and tracking ingestion stop, and despatch halts on the affected lanes. | | | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **What it tracks** | The minimum days remaining across every expiring credential on the connected EasyPost account: the production API key (if a rotation cut-off is set), each linked carrier account's auth grant, and the webhook secret. The card always shows the soonest expiry, because the soonest one is what breaks despatch first. | | **Data source** | Per the card's `detail` ("Days to Token Expiry for the selected period."): computed from the credential metadata Vortex IQ stores when the EasyPost connector is linked, cross-checked against EasyPost's `GET /v2/api_keys` and `GET /v2/carrier_accounts` (the account status and `credentials` fields), plus the connector's own stored key-rotation date. | | **Time window** | `RT` (real time). A live countdown, not a period aggregate. It re-reads on every connector health poll, so a credential rotated this morning updates the dial within minutes. | | **Alert trigger** | `<14 days`. When the soonest credential is within a fortnight of expiry the card turns amber and pages the owner and operations roles. Fourteen days is deliberately generous: it gives time to raise a change ticket, get a new credential issued, and deploy it in a normal release window without an emergency. | | **Why it is a Key Metric card** | A despatch operation that cannot authenticate to EasyPost cannot buy a single label. This is the one Operational Health metric that, at zero, stops the whole shipping pipeline regardless of how healthy every other carrier metric looks. | | **Roles** | owner, operations | ## Calculation Calculated automatically from your EasyPost credential metadata. The card takes the expiry date of every credential attached to the connected account, subtracts today's date (in UTC), and reports the **minimum** across all of them: `days_to_expiry = MIN( credential.expires_at - now() )` across `{api_key, carrier_account_grants[], webhook_secret}`, expressed in whole days, floored. A few mechanics worth knowing: * **EasyPost's primary API key does not auto-expire.** EasyPost issues a test key and a production key that stay valid until you delete or roll them. So in a default single-key setup this card reads a high, effectively static figure (often shown as "no expiry set" or a far horizon) until you schedule a rotation. The card becomes meaningful the moment you set a rotation cut-off, link a carrier account whose grant does expire, or attach a webhook secret with a deprecation date. * **Linked carrier accounts can expire even when the EasyPost key does not.** When you connect a UPS, FedEx or DHL account through EasyPost, the underlying carrier authorisation can lapse (password change, account suspension, OAuth grant revoked). EasyPost surfaces this on the carrier account's status; the card folds the nearest such lapse into the countdown. * **The minimum, not the average.** If your API key has 200 days left but a linked FedEx grant expires in 9 days, the card reads 9. The soonest break is the only one that matters operationally. * **UTC, whole days.** The subtraction is done in UTC and floored, so the figure can be one day adrift from a wall-clock reading taken late in the day in another timezone. See the reconcile section. ## Worked example A UK home-fragrance brand despatches roughly 1,800 parcels a week through EasyPost: rate-shopping across Royal Mail, Evri and DPD on the domestic leg, and using a directly-linked FedEx account for its US and EU orders. Security policy requires the production API key to be rotated every 90 days, and the FedEx grant was last re-authorised on 14 Mar 26. Reading taken at 08:30 BST on 23 Jun 26. | Credential | Type | Expires / cut-off | Days remaining | | ------------------------------------ | ------------- | ----------------- | -------------- | | Production API key (rotation policy) | EasyPost key | 11 Jul 26 | 18 | | FedEx linked account grant | Carrier OAuth | 02 Jul 26 | 9 | | Webhook signing secret | Webhook | 30 Sep 26 | 99 | | **Card reading (minimum)** | | **02 Jul 26** | **9** | The card reads **9 days** and is **amber**: the alert at `<14 days` has tripped. Five things to notice: 1. **The API key is not the problem here, the FedEx grant is.** The key has 18 days; the team's instinct is to look at the key first. But the card is correctly pointing at the FedEx carrier account, whose grant lapses on 02 Jul 26. When that happens, the merchant can still buy Royal Mail, Evri and DPD labels (those are EasyPost-managed accounts), but every US and EU order silently fails rate-shopping and label purchase. The minimum-across-credentials logic is doing exactly its job. 2. **Nine days is enough time to act without drama.** Re-authorising a FedEx account through EasyPost is a few-minutes task in the dashboard, but it needs the FedEx account admin, who may be on leave. Nine days' notice means the change is scheduled, not fire-fought. This is the whole point of a 14-day amber threshold rather than a 1-day red one. 3. **Pair this with the connector's error signals immediately.** If the grant has already started failing intermittently, [API Error Rate](/nerve-centre/kpi-cards/easypost/api-error-rate) and [Tracking API Unavailable / 5xx](/nerve-centre/kpi-cards/easypost/tracking-api-unavailable-5xx) will be ticking up in parallel. A rising error rate on a credential that is also 9 days from expiry is a strong signal the carrier has already begun rejecting it. 4. **Label purchase fails first, not tracking.** When the FedEx grant lapses, new label buys for FedEx lanes fail at the point of despatch, watch [Label Generation Success](/nerve-centre/kpi-cards/easypost/label-generation-success) for the drop. Tracking ingestion for parcels already in flight continues, because those use tracker objects already created. 5. **The webhook secret at 99 days is noise today, but log it.** It is well outside the window now. Note the 30 Sep 26 date so the next rotation is planned and does not become a surprise amber in late September during the run-up to peak. ## Sibling cards merchants should reference together Token expiry is the credential clock. Pair it with the rest of the Operational Health set to see whether a credential is merely approaching expiry or has already started failing: | Card | Why pair it with Days to Token Expiry | What the combination tells you | | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | [API Error Rate](/nerve-centre/kpi-cards/easypost/api-error-rate) | A credential close to expiry that is also throwing errors is already failing, not just ageing. | Low days remaining AND rising error rate means act now, do not wait for the countdown. | | [Tracking API Unavailable / 5xx](/nerve-centre/kpi-cards/easypost/tracking-api-unavailable-5xx) | Distinguishes a credential problem (401 / 403) from an EasyPost-side outage (5xx). | If 5xx is flat but auth errors climb as the clock falls, it is your credential, not EasyPost. | | [Label Generation Success](/nerve-centre/kpi-cards/easypost/label-generation-success) | Label purchase is the first thing an expired credential breaks. | A drop here that coincides with a low expiry count confirms despatch is already affected. | | [Carrier Accounts with Incomplete Credentials](/nerve-centre/kpi-cards/easypost/carrier-accounts-with-incomplete-credentials) | Names which linked carrier account is missing or stale credentials. | Tells you which of your carrier grants is the one driving the countdown. | | [Label Print Failures Spike](/nerve-centre/kpi-cards/easypost/label-print-failures-spike) | The despatch-floor symptom of an auth failure at label time. | A sudden print-failure spike on the day the clock hits zero is the expected failure mode. | | [Rate-Shop API Latency p95](/nerve-centre/kpi-cards/easypost/rate-shop-api-latency-p95) | Carrier auth issues sometimes show first as slow, timing-out rate calls. | Latency creeping up on one carrier near its grant expiry is an early symptom. | ## Reconciling against the source **Where to look in EasyPost's own tooling:** EasyPost is a multi-carrier aggregator, so reconciliation happens in two places: the EasyPost dashboard and the underlying carrier's own account. * **API keys:** [EasyPost Dashboard](https://www.easypost.com/account/api-keys) → **Account Settings → API Keys**. EasyPost lists each test and production key. Standard EasyPost keys do not show an expiry date because they do not expire; the "expiry" this card reports for the key comes from your own rotation policy stored in the connector, not from EasyPost. * **Carrier accounts:** [EasyPost Dashboard](https://www.easypost.com/account/carriers) → **Carriers**. Each linked carrier account shows its status; a lapsed grant shows as needing re-authorisation. Programmatically this is `GET /v2/carrier_accounts`, reading the account status and `credentials` block. * **The underlying carrier portal:** for a linked FedEx, UPS or DHL account, the authoritative expiry lives in that carrier's own developer or account portal (FedEx Developer Portal, UPS Developer Kit, and so on). EasyPost reflects the carrier's state, but the carrier is the source of truth for when a grant lapses. **Why our number may legitimately differ from EasyPost's view:** | Reason | Direction | Why | | --------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **No native expiry on the API key** | Ours can show a number where EasyPost shows none | EasyPost keys do not expire. The countdown for the key is driven by your rotation policy date stored in the connector, so the dashboard shows "no expiry" while the card shows your self-imposed cut-off. This is intentional: the card enforces your policy, not EasyPost's. | | **Timezone / whole-day flooring** | Boundary off by 1 | The card subtracts in UTC and floors to whole days. A grant expiring at 23:30 carrier-local can read one day fewer or more than the dashboard depending on the hour you look. Treat anything inside 2 days as imminent regardless of the exact integer. | | **Credential-metadata refresh lag** | Ours can lag minutes | The card re-reads on each connector health poll. A re-authorisation completed in the EasyPost dashboard updates the card on the next poll, typically within minutes, not instantly. | | **Carrier-side revocation not yet reflected** | EasyPost can lag the carrier | If a carrier revokes a grant out-of-band (account suspension), EasyPost may still show it as active until its next sync with the carrier. Cross-check the carrier portal if the card and carrier disagree. | | **Scan timestamps are carrier-local** | Context only | Unrelated tracking events on the account are timestamped in carrier-local time; the credential clock is UTC. Do not infer the expiry timezone from tracking scan timestamps. | Tracking-event ingestion latency does not affect this card directly (it reads credential metadata, not scans), but the same connector poll cadence that ingests tracking events also refreshes the credential clock, so a connector that is behind on tracking will be slightly behind on this countdown too. ## Known limitations / merchant FAQs **My EasyPost API key never expires, so why does this card exist?** Two reasons. First, most security-conscious merchants set a rotation policy (rotate the production key every 60 or 90 days); the card enforces that self-imposed clock so a rotation never gets forgotten. Second, and more importantly, the carrier accounts you link through EasyPost can expire even when the EasyPost key does not. A lapsed FedEx or UPS grant breaks despatch on those lanes silently. The card watches all of them and shows the soonest. **The card reads a huge number or "no expiry". Is it broken?** No. It means no credential on the account has a near-term expiry: your API key has no rotation policy set, your linked carriers all have healthy grants, and your webhook secret is far out. That is the healthy state. The card only becomes a live countdown once something on the account is genuinely scheduled to expire. **It says 9 days but EasyPost's dashboard shows the carrier account as active. Who is right?** Both, at different moments. EasyPost reflects the carrier's state at its last sync; the carrier's own portal is the source of truth for the actual grant expiry. If the two disagree, trust the carrier portal for the date and re-authorise early. A grant that EasyPost still shows as active can stop minting labels the instant the carrier expires it. **What actually breaks when the clock hits zero?** In order: (1) label purchase for the affected carrier fails first, visible on [Label Generation Success](/nerve-centre/kpi-cards/easypost/label-generation-success) and as a spike on [Label Print Failures Spike](/nerve-centre/kpi-cards/easypost/label-print-failures-spike); (2) rate-shopping drops that carrier, so [Carrier Failover Events (rate-shop rejections)](/nerve-centre/kpi-cards/easypost/carrier-failover-events-rate-shop-rejections) jumps; (3) tracking ingestion for new parcels on that carrier stops, though parcels already in flight keep updating from their existing tracker objects. **Why 14 days for the alert and not 7 or 30?** Fourteen days is the sweet spot for a real despatch operation: long enough to raise a change ticket, find the carrier account admin (who may be on leave), get a new credential issued, and deploy it in a normal release window, without being so far out that the alert becomes background noise people learn to ignore. **Can I get paged sooner for a specific carrier?** The card always shows the single soonest expiry. To see which carrier is driving it, open [Carrier Accounts with Incomplete Credentials](/nerve-centre/kpi-cards/easypost/carrier-accounts-with-incomplete-credentials), which names the specific account. The discipline is: when this card goes amber, immediately check that card to identify the credential, then act on it. **Does rotating my key mid-despatch lose in-flight tracking?** No. Tracker objects already created continue to report scans. Rotating the key affects new label buys and new tracker creation. Best practice is to deploy the new key, confirm a test label buys cleanly, then revoke the old key, so there is no gap. *** ### Tracked live in Vortex IQ Nerve Centre *Days to Token Expiry* is one of hundreds of KPI pulses Vortex IQ tracks across EasyPost 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.