The Token Calendar: how to keep a QuickBooks refresh token alive for an AI agent

This is the guide from the Cortex video on the Token Calendar. It has the same three parts as the video, in the same order:

1. Hourly renewal. The agent renews its access every hour it works.
2. The saved token. Every renewal returns a new refresh token, and the agent saves it straight away.
3. The calendar date. If the agent might sit idle, a person reconnects it before day 100.

The rest of the page explains each part, shows what to check every morning, and gives the reconnect steps for when it breaks anyway.

Why a QuickBooks agent goes quiet instead of failing loudly

Intuit's OAuth2 token notes on GitHub say the access token is valid for one hour and the refresh token for 100 days. A developer guide from Satva Solutions adds that QuickBooks uses OAuth 2.0 only, with no API keys, and that the refresh token rotates.

An agent that writes to your books would hit an error the moment the connection dies. An agent that only reads, which is how we recommend starting, simply stops producing anything. The list of finished jobs nobody billed does not arrive, and unless someone notices the gap, nobody knows why. That silence is the problem this routine solves.

Who this is for and what you need first

This is for service businesses on QuickBooks Online that have, or are about to have, an agent or app reading their books. You need:

• The name of the person who authorized the connection, and a backup who can do it again.
• Access to wherever the builder stores the agent's secrets.
• A shared calendar the office actually reads.
• One report the agent sends you on a schedule, such as a morning list of unbilled jobs. This is how you will see that it is alive.

Part 1, hourly renewal

The access token is what the agent shows QuickBooks on every request, and it lasts an hour. Ask your builder three questions:

• Does the agent renew the access token before it runs out, rather than waiting for a request to fail?
• If a request does fail because the token expired, does it renew once and retry, and stop after that?
• Does it log the time of every successful renewal?

If the answer to all three is yes, part 1 is done. If the agent only runs once a day, it renews once a day, at the start of the run. That is fine. What matters is part 2.

Part 2, the saved token

Each renewal returns a new refresh token, according to Satva's guide. The old one stops being the one to use. So the new value has to be saved before anything else happens.

What good looks like:

• One place. The refresh token lives in one store, not copied into several scripts.
• One writer. Only one process renews at a time. Two copies of an agent renewing at once is a classic way to end up holding a token that no longer works.
• Save, then use. The new token is written to storage before the agent makes its next call.
• A record. The store keeps the time of the last successful save, which is the number you will check.

Part 3, the calendar date

The 100-day clock only matters when the agent stops renewing, for example because it was paused for a slow season, the server was off, or a build was being changed. Put a reminder on the shared calendar at day 90 after the agent's last run whenever it is paused. On that day, someone either runs it once or reconnects it.

Add two more dates while you are there:

• When the person who authorized the connection leaves the company, reconnect under someone who is staying.
• Once a quarter, read the agent's renewal log for a minute. You are looking for gaps.

The morning check (one minute)

Every morning, the agent's list should arrive. If it does not, check in this order:

1. Did the agent run? Look at its last run time.
2. When was the last successful renewal? If it is more than a day old for a daily agent, the connection is the problem.
3. Can QuickBooks still see the app? If not, reconnect.

Two other things look like a dead connection but are not. Satva's QuickBooks limits guide lists about 500 requests per minute per company and 30 operations per batch, and says a throttled call returns error 429. The same guide says webhooks can arrive late or twice, so a good build pairs them with a regular check rather than trusting them alone.

Reconnecting when it breaks

1. The person reconnecting signs in to QuickBooks Online as a user with permission to approve apps for the company.
2. They open the agent's connect link from the builder and approve access for the right company file.
3. The builder confirms the agent saved the new tokens and ran once.
4. You check that the next morning's list arrives.
5. Note the date in the calendar entry, and set the next day 90 reminder if the agent will be paused again.

What the agent should do while you build trust

Start with an agent that reads and drafts. The list of finished jobs with no invoice is a good first job, because your office manager can check every line against the work orders. QuickBooks has agents of its own, and a review by Carly describes them as working inside the ledger, with a "trust, but verify" approach. That advice holds for any agent near your books.

Accuracy is the reason. In the Federal Reserve Banks' 2026 report on employer firms, 46% of small firms using AI named accuracy as a top challenge. A person approving drafts is how you catch the mistakes before a customer does. We explain the approach in human-in-the-loop AI.

How to tell it is working

• The morning list arrives every working day.
• The renewal log has no gaps longer than the agent's schedule.
• There is a day 90 reminder on the calendar whenever the agent is paused.
• Two people in the office know how to reconnect it.

For the full picture of how agents work with QuickBooks, read how an AI agent for QuickBooks works. If you would like someone to look at where an agent fits your books first, your free AI Operations Audit covers it.