Lesson 22.1422.14 When a refresh is refused

In everyday life. A gym membership card works for a month at a time. Each month the gym renews it automatically, and hands over a new card while it takes back the old one. If the member cancels, the next renewal fails. The member does not find out from an error code at the turnstile. The front desk says: "Your membership has ended. Would you like to rejoin?" In this concept, the monthly card is the access token, the automatic renewal is a refresh, and "would you like to rejoin" is the portal's "sign in again".

What you will learn. How a hosted worker keeps working while a person is away, why each refresh replaces the old one, and what the portal does when a refresh can never succeed.

Why it matters. A person who leaves a company must lose access at once, but a brief outage must not lock anyone out. Telling the two apart keeps the worker both safe and usable.

One request, start to finish. On Monday morning, Luis leaves Cedar Ridge. Cedar Ridge's controller, Hannah Price, removes him on the sign-in server, which withdraws his grant. A minute later, a session for Luis that started before his removal makes its next connector call.

1. The session calls the connector. Luis's access token has just expired, so the platform tries to refresh it.
2. The sign-in server refuses the refresh, because his grant was revoked.
3. The platform cannot refresh the credential, and sends the portal a message saying so (22.15).
4. The session reports an authentication error for the connector, and carries on without it, so the worker says it could not reach the AP data.
5. The portal marks Luis's vault as needing sign-in, stops any schedule that uses it, and shows anyone who opens his page: "This account needs to sign in again to use the AP worker."

No stack trace (a raw error report), no retry loop, and no more Cedar Ridge data read for someone who no longer works there. A still-valid access token would have worked until it expired, which is why access tokens are kept short.

Why does a worker need a refresh token?

Chapter 18 kept access tokens short, because a signed token cannot be called back once issued: it works until it expires. So a worker that runs while the person is away needs a refresh token (Chapter 18), a longer-lived token that can be exchanged for a new access token. The right to keep getting new tokens, which the person gave at consent, is their grant (22.11). Refresh tokens and grants come from the core OAuth standard, RFC 6749.

OAuth 2.1, the draft update of the sign-in standard, adds refresh token rotation: each time a refresh token is used, the sign-in server returns a new one and the old one stops working. If a stolen refresh token is ever used, either the thief's or the real holder's next refresh fails, and the theft shows. Chapter 18's sign-in server rotates on every refresh. It also needs the connector's address, resource, on every refresh, as on every sign-in: without it, the new token is one the connector refuses.

A refresh can fail for two kinds of reason, and they need different handling:

To tell them apart, the lab's platform offers a check that reports a credential as valid, invalid (ask the person to sign in again) or unknown (wait and try again). The portal calls it whenever a session reports an authentication error, before it changes anything.

Which question do the documents leave open?

With rotation, every refresh returns a new refresh token. If a platform did not store the new one, its next refresh would use the old one, which no longer works. The platform's documents do not say, so Lab Task 15 tests it.

At work. In Lab 22, Task 16, Claude Code revokes Luis's grant on the staging sign-in server. Then it starts a session for Luis and shows the builder the authentication error in the session's log, the credential check reporting invalid, and the portal's page for Luis showing "sign in again". When Luis signs in and approves consent again, the portal replaces the secret values in his existing credential, because a vault holds one active credential per connector address, and the next session works.

The operating rule: keep access tokens short and refresh tokens rotating. When a refresh is refused for good, ask the person to sign in again and stop that vault's schedules.

Figure 22.20. Issued, refreshed, rotated, refused. A refusal for good becomes "sign in again", not an error.