What is OAuth, and why does my automation keep asking me to reconnect?

What it is, in plain words

Think of a valet key for a car. You hand the valet a key that starts the engine and opens the door, but not the trunk or the glovebox. You keep your own key. If the valet keeps the key too long, you can cancel it without changing the locks.

OAuth is that valet key for your online accounts. When an automation tool asks to “Connect your Google account” and a window opens with an Allow button, that is OAuth. You log in to Google yourself, Google shows you what the tool is asking to do (“read and send email”, “edit your spreadsheets”), and when you click Allow, Google gives the tool a token instead of your password.

Two kinds of token are usually involved:

• An access token, which works for a short time and is what the automation shows with each request.
• A refresh token, which the automation uses quietly in the background to get a new access token when the old one runs out.

As long as the refresh token keeps working, you never see any of this. When it stops working, you see the message every automation owner knows: “Please reconnect your account.”

Why connections stop working

The refresh token is the part that ends. Google’s developer documentation lists the reasons one can stop working, and they map neatly onto what buyers experience:

• Someone removed the access, for example during a security clean-up of connected apps.
• It was not used for six months, for a job that runs only once or twice a year.
• The password changed, for connections that include Gmail permissions.
• Too many live tokens were issued for the same account, so the oldest ones are dropped.
• The app is still marked as “testing” with the provider. Google issues tokens that expire in seven days for those apps, except for basic name and email access. A freelancer who registers their own app for your project and never moves it out of testing gives you an automation that asks to be reconnected every week.
• An administrator restricted the service or set a session length on a company account.

Other providers have their own lists. The pattern is the same: the permission ended, not the automation.

A concrete example

I run scheduled publishing jobs that nobody watches. They are built so that, at the scheduled time, the publishing step needs nothing but a stored token: no browser, no login window. That is what makes unattended runs possible at all, because a login window on a machine nobody is sitting at is a login that never happens.

It also makes the token the single point of failure. In September, the token one of those jobs used to upload images and videos to a code-hosting service stopped being accepted. Five publishing slots in a row, over two days, published nothing. Every scheduled run still reported success, because the job ended normally and the retry step correctly decided that a rejected login is not worth retrying. A separate backup job used the same login and stopped too. The full account is in my scheduled posts stopped for two days, and every job reported success.

That token was not a “Connect with Google” button, but it failed the way an expired OAuth connection fails: quietly, everywhere it was used, and with nothing wrong in the automation’s own logic.

Why it matters when you hire someone

Three things go wrong when the buyer does not know how OAuth works:

1. The connection is made with the wrong account. During a build it is tempting for the freelancer to click Allow with their own account because it is faster. Then the automation reads and sends as them. You will not notice until they close that account or remove the access. The who owns the accounts guide covers how to set this up from the start.

2. Nobody planned for the reconnect. Reconnecting is a two-minute job if you know which connection broke and have the login. It is a support ticket if you do not. A short note at hand-over (which connections exist, which account each uses, how to reconnect) turns every future expiry into a small task.

3. Nobody hears about it. An expired connection usually fails one step, not the whole run. Unless someone built an alert for it, the automation keeps starting on schedule while doing nothing. That is why “run once with a revoked token” is a test in the acceptance checklist for unattended automations.

An API key is the other common kind of access: created on a settings page and pasted in, rather than approved in a pop-up. The API key explainer covers it.

What to ask the freelancer

A good answer is a short table: connection, account, permissions, how to reconnect. Keep it next to the run-book. The next time a window says “please reconnect”, you will know which one, and you will not need anyone’s help.