If the API token expires we silently stop creating tickets, every audit finding goes into the void. Surface 7 days early.
At a glance
The silent-failure tripwire for the Jira connection. Atlassian API tokens expire (typically 1 year for Jira Cloud Personal Access Tokens, or whenever the user manually revokes one); when they do, the Vortex IQ → Jira ticket-creation pipeline stops working with no error visible to the merchant unless a card surfaces it. This card lights up 7 days before the token TTL elapses so the merchant can rotate it before audit findings start dropping into the void.
| What it tracks | Days remaining until the configured Atlassian API token’s expirationTime claim. Pulled from the token introspection endpoint when available, or from the stored created_at + ttl value in the Vortex IQ connector config when introspection is not exposed (e.g. classic API tokens). |
| Token type covered | Atlassian API tokens (Personal Access Tokens, scoped tokens, OAuth 2.0 refresh tokens). Vortex IQ supports all three; the card normalises them to a days_until_expiry integer. |
| Why this is a hero card | Token expiry is silent. Without this card the merchant only discovers the outage when Critical Findings Without a Jira Ticket starts firing, which is 7 days after dispatch failed. By then a typical merchant has 5 to 12 un-dispatched Critical findings sitting un-triaged, each costing measurable revenue. |
| Merchant impact link | Every day past expiry is a day Vortex IQ is detecting issues but not telling the engineering team about them. For a typical mid-sized DTC merchant the cost-of-silent-dispatch-outage runs £200 to £2,000/day in unmitigated revenue risk, depending on what the audit engine catches in that window. |
| Renewal flow | Click the Rotate token button on the card; Vortex IQ opens a deep link to the merchant’s Atlassian token page (https://id.atlassian.com/manage-profile/security/api-tokens), the merchant generates a new token, pastes it back, and the dispatch queue resumes within 60 seconds. |
| Refresh cadence | Every hour. The card does not need second-by-second resolution; an hour-stale TTL is fine because the alert window is 7 days. |
| Time window | RT (current TTL, no period boundary). |
| Alert trigger | token TTL <7 days OR expired. The card shows the countdown with three states: healthy (>7 days), warn (<7 days), critical (expired). |
| Roles | owner, operations |
Calculation
Calculated automatically from your Jira data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading.Worked example
A UK SaaS-merchant hybrid running BigCommerce + Vortex IQ + Jira Cloud, connected for 11 months. Reading taken at 08:15 GMT on 22 Mar 26. The card displays:Atlassian token expires in 4 days (expires 26 Mar 26 at 09:00 UTC) Status: WARN Action: [Rotate token now]What happened and what to do:
- The 365-day TTL is up. When the merchant connected Jira on 26 Mar 25 they generated an Atlassian Personal Access Token with the default 1-year TTL. The card has been showing healthy for 358 days; it transitioned to warn yesterday at the 7-day threshold.
- The cost of doing nothing for 4 days. On 26 Mar the token expires; dispatch goes silent. Audit-cycle frequency for this merchant is 6 hours, so within 6 hours of expiry the first Critical/High finding starts queuing un-dispatched. By day 7 of silence (02 Apr 26), Critical Findings Without a Jira Ticket lights up with the first un-ticketed Critical, by then the merchant has missed roughly 7 to 14 un-dispatched findings (mix of severities) over a 7-day window. For this brand’s audit profile the historical pattern is 1 to 2 Critical and 4 to 6 High per week.
- The rotation is 90 seconds of work. Click the in-card Rotate token button: Vortex IQ deep-links to Atlassian’s token page, the merchant clicks Create API token, names it
Vortex IQ - 26 Mar 26, copies the value, pastes back into Vortex IQ, clicks Save. The card flips back to healthy (TTL ~365 days) within 60 seconds. - The post-rotation verification. Open Finding-to-Ticket Dispatch Lag, it should drop to its baseline (typically <2 minutes p95) immediately. If it doesn’t, the new token has a permission scope problem; click Test connection on the connector page and the API call surfaces the specific error.
Sibling cards merchants should reference together
| Card | Why pair it with Atlassian Token Expiry Imminent | What the combination tells you |
|---|---|---|
| Critical Findings Without a Jira Ticket | The downstream effect when this card is ignored. | Token expired plus this card non-zero is the same incident, fix the token; tickets back-fill automatically. |
| Finding-to-Ticket Dispatch Lag | The latency-side companion. | Lag spikes to infinity when the token expires, lands back at baseline post-rotation. |
| Rate-Limit Exhausted | The other major dispatch-failure root cause. | If both fire simultaneously, address rate-limit first (back-off), then rotate token. |
| API Rate-Limit Headroom | Real-time throttling state. | Healthy headroom plus expired token equals straightforward token rotation; squeezed headroom plus expired token equals coordinate rotation timing to avoid bulk-create stampede on resume. |
| VortexIQ Findings Open | The accountability-side dial. | After token rotation, expect a brief uptick in this card as queued un-dispatched findings flush through. |
| Cross-connector: GA4 Property Health, Datadog Health Score | Other connector-side health peers. | The full connector-health row of the dashboard; if multiple are amber, do a global token-rotation audit. |
| Cross-connector: GitHub Token Expiry | The same TTL pattern on a different connector. | Many merchants rotate Atlassian and GitHub tokens together; a coordinated rotation cadence avoids cross-cancelling outages. |
Reconciling against the vendor’s own dashboard
Where to look in Atlassian: The token-management surface is on Atlassian’s profile page, not Jira itself:https://id.atlassian.com/manage-profile/security/api-tokensThis page lists every Atlassian API token attached to the user’s account, with name, last-used timestamp, and TTL. The token Vortex IQ uses appears with the name set at connector setup (default
Vortex IQ Connector). The Atlassian page shows TTL in absolute terms (e.g. Expires 26 Mar 2026); this card converts that to a remaining-days countdown.
Why our number may legitimately differ from Atlassian’s display:
| Reason | Direction | Why |
|---|---|---|
| Refresh cadence | Ours up to 1 hour stale | The card polls hourly; Atlassian’s page is real-time. If a merchant manually shortens or revokes a token, the card catches up on the next poll. |
| Time zone | Ours in UTC, Atlassian in user-local | Atlassian’s page uses the user’s browser timezone for the Expires date; the card uses UTC. The day-count is unaffected; the displayed date may differ by 1 day either side of midnight. |
| OAuth refresh-token sliding window | Ours overstated for OAuth | OAuth 2.0 refresh tokens auto-extend on use. If the connector is actively refreshing, the effective expiry is later than the originally-issued TTL. The card uses the most recently-issued TTL, which is conservative. |
| Atlassian site-level revocation | Ours overstated immediately after revocation | If an Atlassian site admin revokes all user tokens (e.g. during a security incident), the token is dead instantly but the card may show 30 to 60 minutes of stale TTL until the next poll fails and the card flips to expired. |
| Personal Access Token vs API Token | Same numeric, different wording | Atlassian transitioned the API token product; older tokens may show “API Token” on Atlassian’s UI while newer ones say “Personal Access Token”. Both are the same thing for this card’s purposes. |
| Card | Expected relationship | Causes of legitimate divergence |
|---|---|---|
github.gh_token_expiry_days | Same pattern, different vendor. | Independent TTLs, no mathematical relationship, but operational best practice is to rotate together to avoid back-to-back outages. |
shopify.shopify_session_health | Adjacent connector-token-health peer. | Different auth mechanism (Shopify uses OAuth-issued shop tokens with no fixed TTL); not a reconciliation. |
| Vortex IQ Connector Health Index | This card is one input. | Multiple connector tokens nearing expiry simultaneously degrades the index; a coordinated rotation campaign clears it. |
Known limitations / merchant FAQs
Why does the token expire at all? Can I make it permanent? Atlassian Cloud tokens have a maximum TTL of 1 year for security reasons (Atlassian Cloud security baseline, no override available). Self-hosted Jira Server / Data Center allows infinite-TTL Personal Access Tokens, but that’s not the typical Vortex IQ deployment. The 1-year cycle is a feature, not a bug, it forces a periodic credential audit. My token expires in 4 days but it’s the weekend. Can I rotate Monday? Technically yes (4 days > 0), but the safer pattern is to rotate the moment the alert fires. Atlassian periodically pushes early-expiry events for tokens that haven’t been used in 14+ days, the displayed TTL is not always the actual TTL. Rotate when prompted. The card says expired but Vortex IQ is still creating tickets. How? Most likely cause is a stale poll, the card hasn’t refreshed since you rotated. Wait 60 minutes for the next poll, or click Refresh now on the card. Less likely: Atlassian sometimes honours a brief grace period (typically 24h) on expired tokens for operations in flight; the card cannot see that grace. What’s the difference between a Personal Access Token and an OAuth flow? Personal Access Tokens (PATs) are simpler and more common; they’re long-lived, scoped to a user, and revocable from Atlassian’s profile page. OAuth 2.0 flows require an Atlassian-registered app and use refresh-token rotation, more complex but better for multi-tenant SaaS. Vortex IQ supports both. PATs are the default; switch to OAuth in Settings → Connectors → Jira → Auth Method if you operate multiple Vortex IQ tenants on a single Atlassian account. I rotated the token but dispatch is still failing. What now? Five-minute checklist. (1) Click Test connection on the connector page, the API call returns the specific error code. (2) Verify the token’s user hasBrowse Projects, Create Issues, Edit Issues, Add Comments permissions on the destination project. (3) Verify the custom field Vortex IQ Finding ID exists and is on the project’s issue-create screen. (4) Check Rate-Limit Exhausted, the rotation may have triggered a stampede that’s being throttled. (5) If still failing, the new token may be missing a scope, regenerate with the Default scope, do not select narrower scopes.
Does this card track every Atlassian token I have, or just the one Vortex IQ uses?
Just the one Vortex IQ uses. If your team has 50 Atlassian tokens for various integrations, this card only watches the one configured in the Vortex IQ connector. The Atlassian profile page is the source of truth for the full list.
Why do I need to rotate manually? Can Vortex IQ rotate automatically?
Atlassian’s API token endpoint requires the user’s browser-session for POST /tokens, there’s no API for programmatic creation. The merchant must click through the Atlassian token-creation UI. Vortex IQ deep-links to the right screen and pre-fills the recommended name to make it 90 seconds of work, but the human step is mandatory. OAuth 2.0 flows do auto-refresh, switch to OAuth if rotation friction is recurring.
The alert window is 7 days. Can I make it 14 or 30?
Yes, in Settings → Alerts → Jira Token Expiry. The default 7-day threshold is calibrated for typical merchant ops cadence; teams that handle credential rotations on monthly tickets often prefer 30 days of advance warning. The trade-off: longer windows mean amber-state for longer, with potential alert fatigue.
My token was revoked by my Atlassian site admin during a security audit. What happens?
The card flips to expired (critical) within an hour. Dispatch silently fails. Coordinate with the admin to issue a replacement, then click Rotate token and paste the new value. Audit findings filed during the outage queue and dispatch on resume; nothing is lost, but Critical Findings Without a Jira Ticket will fire on day 7 of the outage if not resolved.