At a glance
Days remaining until the Royal Mail OAuth client credential expires. When this hits zero, label generation stops, tracking events stop ingesting, and claims-API access goes dark. The “the connector silently broke” early-warning.
| What it counts | (token_expires_at - NOW()) / 86400. Real-time snapshot read from the OAuth token cache; refreshed each authenticated call. |
| API endpoint | OAuth client-credentials grant on POST /token. The Royal Mail Shipping API and Tracking API both use OAuth 2.0 with 1-year token lifetimes by default. Tokens are reissued by rotating the client secret in the Royal Mail Developer Portal. |
| Service-tier scope | Connector-level, not per-shipment. A single token covers all Royal Mail services the merchant has subscribed to (Shipping API, Tracking API, Claims API). |
| Tracked vs untracked | Both. Token expiry breaks all label generation, tracked and untracked alike. Untracked label generation via Click & Drop Web does not require the API token; only the Shipping API integration does. |
| Return-leg inclusion | Both directions; same token covers outbound and Tracked Returns. |
| Geographic scope | Global; the OAuth token is account-wide, not per-region. |
| Token-rotation cadence | Royal Mail recommends rotating annually or on staff-departure. Tokens issued before April 2024 had 18-month default; new integrations get 12 months. |
| Currency | N/A (this is an operational health card, not a financial card). |
| Time window | RT (real-time, snapshot at last sync). |
| Alert trigger | <14 days (raise an alert 14 days before expiry). The 14-day window gives operations 2 weeks to coordinate with the developer-portal admin to rotate the secret without service interruption. |
| Roles | owner, operations |
Calculation
Calculated automatically from your Royal Mail data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading.Worked example
Same UK DTC homewares brand. Reading taken at 09:00 BST on 12 Mar 26.| Field | Value |
|---|---|
| Token issued | 14 Apr 25 |
| Token expires | 14 Apr 26 |
| Days remaining | 33 |
| Last refresh attempt | 12 Mar 26 09:14 (success) |
| Connector status | Healthy |
<14 days is not tripped, but the merchant is in the planning window. Five things to notice:
- The 14-day threshold is the planning trigger, not the failure trigger. Royal Mail’s developer portal requires a multi-step rotation: generate a new client secret, deploy it to the production secret store, fail-over connector requests to the new secret, revoke the old one. For a brand running on a single Royal Mail integration the rotation takes 1 to 2 hours of dev time + a 24h confidence window; the 14-day buffer is for diary-coordination, not engineering work.
- Most merchants miss the renewal because Royal Mail does not email the API admin. The developer-portal account that owns the API token is often not the same person as the Royal Mail Business Account holder; the renewal reminder goes to whoever clicked “create application” in the dev portal years ago. This card is the merchant’s belt-and-braces against that gap.
- Failure mode is silent. When the token expires, Shipping API calls return 401; the connector cannot generate labels, the merchant’s order-fulfilment automation halts. The Royal Mail status page does not show this as an outage because the API itself is up. Customer-service tickets pile up before anyone connects the dots; this card pre-empts the discovery.
- The “rate suddenly degraded” pattern for token expiry. A merchant on this brand once let the token expire on 22 Dec at 14:00; the resulting 6-hour outage on the busiest pre-Christmas afternoon caused 1,200+ delayed parcels and an estimated £18k of make-goods. The card’s purpose is to make this never happen again.
- Compare to Evri token cadence. Evri’s API uses 90-day token lifetimes (much shorter than RMG’s 12 months) but the API client auto-refreshes on 401; failure mode is different. See
hermes_evri.her_auth_token_expiry_days.
Sibling cards merchants should reference together
Token expiry is an ops-health metric. Pair it with these to catch and resolve connector failures:| Card | Why pair it with Token Expiry | What the combination tells you |
|---|---|---|
| API Error Rate | The downstream symptom when the token expires. | A token at 0 days + a spike in 401 errors = the rotation did not happen on time. |
| Label Generation Success | The customer-facing impact of an API outage. | Label success drops to 0 percent within minutes of token expiry; this card pre-empts the drop. |
| On-Time Delivery Rate | The downstream business impact. | A multi-hour token outage delays label-print, which delays carrier-handover, which drops OTD 1 to 2 days later. |
Cross-connector: hermes_evri.her_auth_token_expiry_days | Adjacent carrier with a different token model. | Both should be monitored on the same operations dashboard. |
| Cross-connector: any other connector’s token-expiry card | Same operational pattern across all OAuth connectors. | A unified ops dashboard should surface all expiry-window connectors at once. |
Reconciling against the vendor’s own dashboard
Where to look in Royal Mail’s own portal: Royal Mail Developer Portal → My Apps → [Your App Name] → Credentials lists the token issued, expiry, and last-rotated dates. This is the only authoritative source; the Click & Drop merchant portal does not surface API-token state. Why our number may legitimately differ from Royal Mail’s portal:| Reason | Direction | Why |
|---|---|---|
| Timezone (BST vs UTC) | Boundary days off | The dev portal renders expiry in UK local; the card uses UTC. Boundary-day shifts may move the count by 1 day on the cutover. |
| Sync lag | Ours can lag 4h | Token-expiry sync runs every 4 hours by default. If the secret was rotated in the last 4 hours, the card may still show the old value. |
| Multi-secret state | Either | If the merchant operates 2 secrets simultaneously (during a rotation window), the card shows the soonest-expiring; the dev portal shows both. |
| Cross-connector reconciliation | N/A | Each connector has its own OAuth lifecycle; tokens do not reconcile across connectors. |
| Card | Expected relationship | Causes of legitimate divergence |
|---|---|---|
hermes_evri.her_auth_token_expiry_days | Adjacent carrier; independent OAuth lifecycle. | Different token TTLs (Evri 90 days, RMG 12 months). |
Known limitations / merchant FAQs
What happens if we miss the rotation window? Label generation stops the moment the credential expires. New consignments cannot be booked through Royal Mail OBA or Click & Drop API. Existing in-flight consignments continue to deliver and tracking events continue to flow until Royal Mail-side cleanup, but no new dispatch is possible. Recovery is roughly 30 to 90 minutes once a new credential is issued and connected; same-day recovery is feasible if the rotation is started before 13:00 GMT (before Royal Mail’s mid-afternoon dispatch cut-off). Who needs portal access to rotate? The Royal Mail OBA account holder (the named contractual contact) or a designated administrator on the OBA contract. Most merchants set up a shared ops-team email for the OBA login and bring multiple ops-team members onto the account; this avoids the situation where the only person who can rotate is on holiday. Royal Mail OBA’s portal session times out after 30 minutes of inactivity, so the rotator should be prepared to complete the cycle in one sitting. Why does the alert fire at 14 days, not 7 or 30? Operational realism. 30 days is too noisy, with the alert sitting orange for a month. 7 days is too tight for typical UK ops cadences, especially on weekend / bank-holiday boundaries (UK has more bank holidays than most countries; 7 days can easily span 5 working days). 14 days gives a clean two-week calendar slot, includes one full Saturday-Sunday gap, and matches what most UK ops teams use for similar credential trip-wires. Override per-workspace if needed. Royal Mail rotated my OBA credential without warning. Why did the card not catch it? Two scenarios. (1) Routine rotation: Royal Mail does not pre-announce credential rotations on most OBA contracts; the card relies on the credential metadata stored in the connector. If Royal Mail rotated server-side without issuing a new credential to the merchant, the card reads the old expiry until the next API call fails with a 401. The first symptom is a spike inroy_api_error_rate, not in this card. (2) Compromised-credential revocation: if Royal Mail flagged the credential as compromised and revoked early, ditto. Treat any sudden 401 / 403 spike as urgent regardless of this card’s reading.
Can we automate Royal Mail credential rotation?
Not as of 02 May 26. Royal Mail OBA does not currently support programmatic API-key rotation; the rotation is a manual portal action via OBA’s secure portal. OAuth-mode integrations (where supported on newer Royal Mail APIs) auto-refresh access tokens silently, but the underlying client-credential rotation remains manual. The card surfaces a 14-day reminder; that is the automation today.
Does the UK Royal Mail strike action affect credential rotation?
No directly, the OBA portal remains operational during industrial action. However, rotation timing should account for strike days because dispatch volume cannot be redirected easily during a strike (alternative carriers absorb capacity slowly). Rotate during a quiet, non-strike window when possible; a botched rotation during a strike is harder to recover from because customer-experience tolerance is already strained.
The card says 14 days but the new credential was issued yesterday; why has it not reset?
Two possible reasons. (1) The new credential has not been pasted into the Vortex IQ connector yet; the card reads the connected credential, not the most-recently-issued portal credential. (2) Card cache: read-time is sub-minute, but stale-cache windows of up to 5 minutes have been observed on Royal Mail-API-edge during their portal-side propagation. Check the Vortex IQ connector settings and update if needed.
What if we have multiple Royal Mail OBA contracts (different rate cards, different cohorts)?
Each OBA contract has its own credential and its own expiry. The card surfaces the credential of the connected integration only. If the merchant runs multiple OBA contracts (DTC + B2B reseller, retail + wholesale), set up each as a separate Vortex IQ Royal Mail connector; each card surfaces its own count.
Does this card behave differently during Q4 peak?
No. The credential lifetime is independent of dispatch volume. However, the operational cost of expiry is much higher during peak (a half-day of label-generation downtime in early December is catastrophic in a UK retail context, vs absorbable in March). Strongly consider an early rotation if the credential expires inside the November-December peak window. Rotate in October to give a clean buffer through Black Friday, Cyber Monday, and the Christmas dispatch deadlines.
Royal Mail’s Click & Drop and Pro Shipping APIs use different credentials. Which one does this card track?
The card tracks whichever credential is connected to the Vortex IQ Royal Mail integration. Most merchants connect Pro Shipping (the OBA-tied production API); Click & Drop is typically used for smaller volumes via the merchant-facing portal. If both are connected via separate integrations, each gets its own card. Check the connector settings to confirm which API is connected.
Can we monitor multiple credentials in one dashboard?
Yes; the connector-management area lists all connected integrations with their token-expiry-days. The card here is the per-connector view; the cross-connector view sits on the connector-management page. Multi-carrier merchants (Royal Mail + DPD + Parcelforce) should pin all three credential cards on a single ops-calendar view to coordinate rotations into one quarterly sweep.
My ops team rotated the credential but new shipments still fail. What did we miss?
Three usual causes. (1) Cache lag: the connector reads the new credential but Royal Mail’s edge may take up to 30 minutes to propagate the new credential to dispatch endpoints. Wait 30 minutes and retry. (2) Pasted wrong credential: easy to copy-paste the previous credential by mistake; verify in connector settings against the OBA portal. (3) Service-level mismatch: Royal Mail’s OBA contract specifies which services (Tracked 24, Tracked 48, Special Delivery) are enabled; if the new credential was issued under a different OBA contract that excludes a service you use, label generation fails for that service specifically. Confirm the new credential is for the same OBA contract as the old.