Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages

Help for owners

My app keeps losing its Xero connection and says the token expired

Short answer

Xero access tokens last 30 minutes, so an app must renew its login constantly. Xero says unused refresh tokens expire after 60 days and that you must replace the old refresh token with each new one. A drop usually means the app did not save the new token or sat unused too long.

  • Written for business owners
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Does this sound like your situation?

  • The app says the Xero token has expired or is invalid, and asks me to log in again.
  • It works for a few days after I reconnect and then fails.
  • The error mentions an invalid grant or unauthorised.
  • It breaks after a restart, a new server or a deployment.
  • A seasonal tool stops every time it sits unused for a while.

Why does this happen?

  1. Access tokens are short-lived on purpose

    Xero states that access tokens expire after 30 minutes, and that standard integrations rely on refresh tokens to get new ones. So every working connection is renewing itself all the time, without you.

  2. The new refresh token was not saved

    Xero says that when you refresh, you should replace your existing refresh token with the new one returned. An app that keeps the old one, or loses the new one on restart, fails at the next renewal.

  3. It sat unused for too long

    Xero states that unused refresh tokens expire after 60 days, after which the user has to authorise the app again. A tool that runs rarely or only at certain times of year hits this.

  4. A renewal ran twice at once

    Xero states that if no response is received you can retry refreshing the existing refresh token for a grace period of 30 minutes. Two servers or workers refreshing at the same time can each end up holding a different token, and one is rejected.

  5. Someone changed the connection on the Xero side

    If the user who authorised it is removed or the app's access is removed in Xero, the next renewal fails until someone authorises again.

What can I do about it today?

  1. Note the date of each dropAnd what happened just before: a deployment, a restart, a long quiet period or a staff change.
  2. Find who authorised the connectionIn Xero, check that person still has access to the organisation.
  3. Ask whether more than one copy runsA test site or second server using the same Xero connection is a common cause.
  4. Reconnect once, not repeatedlyRepeated reconnects while two copies run can keep breaking each other.
  5. Send the notes to your developerThe dates, the exact error text and a screenshot of the connection message.

When should I bring someone in?

  • The connection drops more often than every couple of months.
  • Invoices or bank lines are not arriving between drops.
  • No one knows where the app keeps its Xero login.

How do I handle it?

  1. Find every copy of the connectionI read the vendor's current documentation first, and every change is tried on test data before it touches your real books. I list each place that holds a Xero login, live, test and old.
  2. Store the renewed token properlyThe new refresh token is saved before it is used and only one renewal runs at a time, with the 30 minute retry window handled.
  3. Keep it from going idleA scheduled renewal keeps the connection alive within Xero's expiry limit.
  4. Make failure visibleAn expired or rejected token pauses sending and tells you, so nothing is lost silently.

The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.

What do owners ask about this?

Can I get a token that never expires?

Xero states it does not offer long-lived access tokens, so standard integrations rely on refresh tokens.

What does invalid grant mean?

It generally means the refresh token was rejected, for instance because it was already replaced or has expired. The app must then be authorised again.

Do I lose data when it drops?

Data in Xero stays. Anything the app tried to send while locked out may be missing until it is sent again.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.

For your developer: the technical fixes

Next step

Want this off your desk?

Send me a few lines on where things stand. I reply within 24 hours.