> ## 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, Deutsche Post > Days to Token Expiry for Deutsche Post 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 ## At a glance > Days remaining until the DHL Geschaftskundenportal API credential behind your Deutsche Post connection stops authenticating. When the token expires every booking, label-generation, tracking-event ingestion and Reklamationsstelle claim call from Vortex IQ to DHL fails with HTTP 401 at once. Nothing is wrong with delivery itself; the connector simply goes dark. The hero placement exists because an expired credential takes the whole despatch operation offline with no gradual warning, only a 14-day countdown. | | | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **What it tracks** | `expiry_at - now()` in whole days, where `expiry_at` is the expiry stamped on the active DHL credential held in the integration secret store. Negative values clamp to 0 ("expired"). | | **Data source** | Stored credential metadata, not a live DHL call. The DHL Geschaftskundenportal uses an OAuth-style `client_id + client_secret + access_token + refresh_token` pattern; the access token rotates roughly hourly and refreshes automatically, the refresh token carries the multi-month horizon this card reports. Per `detail`: "Days to Token Expiry for the selected period." | | **Time window** | `RT` (real time). A live countdown, recomputed on each connector heartbeat, not a windowed aggregate. The figure is current to the last sync (typically within minutes). | | **Alert trigger** | `<14 days`. Fires when fewer than 14 days remain. Fourteen days covers a despatch team's two-week planning cadence and leaves room to find whoever holds the DHL portal login before the credential lapses. | | **Roles** | owner, operations | | **Why it is a hero** | Token expiry is the most common "the connector just stopped working" support ticket. Unlike a delivery dip it gives no gradual signal: the day the credential dies, every downstream card (label success, tracking ingestion, OTD) goes stale at the same moment. | ## Calculation Calculated automatically from your Deutsche Post connection metadata. The connector records the expiry returned by the DHL token endpoint each time it authenticates, subtracts the current time and floors to whole days. Three credential horizons can drive this number, and the card always shows the **nearest actionable** one: 1. **Access token.** Short lived (roughly one hour for the DHL flow). The connector refreshes these automatically, so they self-heal and are never the headline. 2. **Refresh token.** The medium horizon. For the standard Vertragskunden OAuth setup the refresh token carries a multi-month life (commonly around 12 months) and must be renewed by re-authorising the connection through the portal. 3. **API key / app registration.** Older Online-Frankierung integrations may use a longer-lived API key on a fixed rotation. These do not expire on the OAuth clock but can be revoked or flagged for periodic review; the connector treats a known review date as an expiry horizon. The headline is `floor(min(refresh_expiry, key_review_date) - now)` in days. The auto-refreshing access token is deliberately excluded, because reporting it would peg the card near 0 and make it useless. ## Worked example A Dusseldorf-based DTC homeware merchant, around 6,400 parcels per week, ships almost entirely on DHL Paket (Inland) with a DHL Paket International leg for AT and CH orders. They connected Deutsche Post to Vortex IQ via the standard Geschaftskundenportal OAuth flow. The refresh token was issued on 12 Mar 25 with a 12-month rotation, due to expire on 12 Mar 26. Reading taken at 09:00 CET on 27 Feb 26: | Credential horizon | Expiry / review date | Days remaining | | ------------------------------------------ | -------------------- | -------------- | | Access token (auto-refresh) | 27 Feb 26, hourly | 0 (self-heals) | | Refresh token (OAuth) | 12 Mar 26 | 13 | | API key production review | n/a (OAuth setup) | n/a | | **Nearest actionable horizon (this card)** | **12 Mar 26** | **13** | The card reads **13 days**. The alert at `<14 days` is **tripped**: the dashboard turns amber and the integration owner is emailed. Four things to notice: 1. **The access token does not drive the number.** It expires hourly and refreshes silently. If the card reported that it would always read 0. The card correctly reports the 13-day refresh-token horizon. 2. **The rotation playbook is short, run it now.** Log into the [DHL Geschaftskundenportal](https://www.dhl.de/de/geschaeftskunden.html), open **Einstellungen, Entwickler, API-Zugang**, generate new access credentials, copy the `client_id` and `client_secret`, paste them into Vortex IQ under Integrations, Deutsche Post, Update Credentials, then test the connection. Five to eight minutes for a familiar user. The portal lets old and new credentials overlap briefly, so there is no hard cutover. 3. **When this hits 0, these cards go stale, not red.** Label Generation Success, Retouren-Etikett Generation Failure Rate, On-Time Delivery Rate and every tracking-driven card stop receiving fresh data. They do not show a delivery problem; they show no new data. Bookings fail loudly with 401; tracking fails silently until someone notices missing scans. 4. **Peak timing matters.** This token expires 12 Mar 26, clear of Q4. A merchant whose credential would lapse in late November should rotate in October rather than risk a re-consent during Black Friday week, when nobody has time to chase a portal login. ## Sibling cards merchants should reference together Token expiry is an availability metric, not a performance one. Pair it with the other operational-health and label cards to understand blast radius: | Card | Why pair it with Days to Token Expiry | What the combination tells you | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | [API Error Rate](/nerve-centre/kpi-cards/deutsche-post/api-error-rate) | A credential being throttled or partially revoked shows up as a rising 401 / 403 share first. | A creeping error rate while this card still reads positive days usually means the credential is being de-permissioned, not cleanly expiring. | | [Label Generation Success](/nerve-centre/kpi-cards/deutsche-post/label-generation-success) | Label creation is the first surface to break when auth fails. | If label success collapses to near zero at the same moment this card hits 0, the cause is the token, not the label payload. | | [On-Time Delivery Rate](/nerve-centre/kpi-cards/deutsche-post/on-time-delivery-rate) | OTD depends on fresh delivered scans, which stop arriving when the token dies. | OTD flat-lining at its last value while this card hits 0 is a data-availability artefact, not a delivery improvement. | | [Late Shipments](/nerve-centre/kpi-cards/deutsche-post/late-shipments) | Counts freeze rather than continue updating after expiry. | A frozen late count plus a token at 0 means you are looking at stale data, not a calm network. | | [Exception Rate](/nerve-centre/kpi-cards/deutsche-post/exception-rate) | Stale tracking ingestion from a dead token can masquerade as a sudden exception-rate change. | A frozen exception rate plus a token at 0 means stale data, not a real network event. | | [Open Claims](/nerve-centre/kpi-cards/deutsche-post/open-claims) | Reklamationsstelle claim sync shares the same credential. | An expired token stops new claims being filed and status changes being read; treat expiry as a finance-data event, not just an ops one. | ## Reconciling against the source **Where to look in DHL's own tooling:** The authoritative record of credential validity is the [DHL Geschaftskundenportal](https://www.dhl.de/de/geschaeftskunden.html), under **Einstellungen, Entwickler, API-Zugang**, which lists active and expired credentials with `Erstellt am` (created), `Gultig bis` (valid until) and `Letzte Nutzung` (last used). The [DHL Developer Portal](https://developer.dhl.com/) holds the application registration and consumer key for the underlying API app. The card reading should match the active credential's `Gultig bis` to within a day; if it differs by more than a day, force a refresh under Integrations, Deutsche Post, Refresh Credentials. There is no aggregator layer here: Deutsche Post / DHL is a single national carrier, not an EasyPost or Shippo style multi-carrier API, so the only two sources of truth are the two DHL portals above. If you run DHL behind an aggregator, reconcile against the aggregator's connection-health page as well. **Why our number may legitimately differ from DHL's portal:** | Reason | Direction | Why | | -------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Timezone (CET/CEST vs UTC)** | Boundary day off by one | The portal shows expiry in Berlin local time; the card computes against UTC and floors to whole days. Near a midnight boundary the two can differ by one day. Scan and event timestamps elsewhere in the connector are likewise in carrier-local time. | | **Credential-event ingestion latency** | Ours can lag briefly | The card refreshes its horizon only on a successful authentication. If an external system rotates the credential, our cached expiry stays stale until our next authentication picks up the new value. Credential metadata arrives in the same batched cadence as tracking events. | | **Manually revoked credential** | Ours higher until first 401 | If the credential is revoked early in the portal, the card may keep reading the original horizon until the next sync; the first 401 forces a re-read. | | **Multiple active credentials** | Either | A merchant may hold separate production and sandbox pairs; the card reads whichever is bound to the live integration. Confirm you are comparing the production credential. | | **Refresh token vs API key** | Different horizons | The portal may show an API key with no fixed expiry while the card reports the OAuth refresh-token horizon, which is the one that actually breaks despatch. | ## Known limitations / merchant FAQs **My token rotates every 12 months. Why does the alert fire 14 days early?** The 14-day window is the safe buffer for a human-led rotation. Leaving it to the day before gives under 24 hours to log in, generate, paste, test and verify, which is too tight for a Friday afternoon. Fourteen days lets you schedule the work and recover from a failed test. If your operations cadence supports it, the threshold can be tightened to 7 days per store; below 7 is operationally risky. **The card says "expired" but my Deutsche Post integration still works. Why?** Three possibilities. (1) Sync lag: the card is reading a cached expiry, so force a refresh. (2) Overlapping credentials: the portal often lets an old and new pair co-exist for 24 to 48 hours after rotation. (3) Wrong credential record: if an integration was disconnected and reconnected, a dead record may still be read, so reconnect to be safe. **What exactly stops working when this hits 0?** Everything that calls DHL: new shipping labels, Retouren-Etikett (return label) generation, rate quotes, tracking-event ingestion and Reklamationsstelle claim sync. Parcels already in the DHL network keep moving physically; you simply stop getting scans and cannot create new labels. The visible symptom is several cards freezing at their last-known values at once. **Can I rotate the credential before the alert fires?** Yes, and that is the preferred pattern. Set a recurring reminder (for example every quarter, aligned to a quiet trading week) and rotate proactively. The Geschaftskundenportal generates new credentials without invalidating the old ones immediately, so there is no outage during rotation. **My API credentials were generated by a colleague who has left. Should I rotate?** Yes, immediately. Generation is bound to a Geschaftskundenportal user; if that account is deactivated the credentials can stop working without notice. Best practice is to generate against a shared operations service account rather than a personal login, and rotate whenever the binding user changes role. **Does the alert fire on access-token or refresh-token expiry?** Refresh-token. Access tokens expire roughly hourly and refresh automatically, so the card does not surface them. The refresh token carries the multi-month horizon and requires re-authorisation when it lapses. For most Deutsche Post merchants this is a once-a-year, structural event per integration. **The portal shows my credential as "Aktiv" but the card says expired. Who is right?** The card. It reads the `expiry_at` stamped on the credential; if DHL has not yet run its housekeeping at the expiry moment the portal may still show "Aktiv", but every API call after that point fails with 401. Trust the card and rotate. **Can I get a webhook instead of an in-dashboard alert?** Yes. The integration-health alert framework delivers to Slack, Teams or email. Configure it once at integration level; the same trigger that lights this card fires the webhook. Many German operations teams route these to a dedicated integration-health channel. *** ### Tracked live in Vortex IQ Nerve Centre *Days to Token Expiry* is one of hundreds of KPI pulses Vortex IQ tracks across Deutsche Post 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.