Building a Gmail analytics Actor, the first real decision was not the report format. It was the authorization model. In a multi-tenant context, OAuth stops being purely a security question and becomes a product friction question.
I ended up with refresh-token-only instead of running a full 3-legged flow on every invocation. The reasoning is mundane and practical.
The operational reality of an Actor
Actors mostly run from schedules or non-interactive pipelines. If every run requires a fresh human consent, the automation degenerates into manual labor. That single decision quietly eats the entire value of the tool.
You can model this as a unit-economics question: every extra interactive consent step is a tax on every future run. With a refresh-token model, the human pays the consent cost once, then the workflow runs free.
Why not "platform-managed" delegated access
A natural shortcut is "let the platform manage it" — store user credentials centrally, never bother the user again. I avoided this on purpose.
The category of data here (inbox content) is sensitive by default. I do not want the product to be designed around "trust me first." I prefer a verifiable model: explicit user authorization, controllable scope, revocable token, recoverable failure path. Anything that requires the user to extend trust beyond what they can audit is a future incident waiting to happen.
Refresh-token-only as an observability win
There is a less-obvious reason refresh-token-only works well in multi-tenant. Failure modes converge.
Common errors collapse into a small, named set:
- token expired
- scope insufficient
- API rate-limited
Instead of a tangle of callback/session/browser-state issues. As the maintainer, this kind of observability matters more to me than a flow that "looks more standard." Production debugging is dominated by the worst few failure modes; making those modes obvious is worth a lot.
Privacy posture
Take the minimum usable data, not the maximum available data. Functionality can grow slowly. Authorization boundaries should be clean from day one. Once you have taken too much, pulling back is almost always painful — and visible to the customer in a way that reads as a downgrade rather than a fix.
This is a small mindset thing that compounds. Every new feature decision starts from "what is the smallest scope that lets this work?" instead of "what scope unlocks the most options?"
Three questions before you copy this
If you are working on multi-tenant automation, the three useful questions are:
- Is your flow interactive, or batch?
- Are you optimizing for first-run experience, or long-run stability?
- Are you building trust through marketing language, or through revocability and audit boundaries?
The answers reorder a lot of design choices. For my Actor — scheduled, multi-tenant, sensitive scope — refresh-token-only was not the flashiest choice. It was the one that matched how Actors actually run: schedulable, maintainable, explainable.
Closing
Refresh-token-only is not a clever pattern. It is a boring one. Boring is what you want from authorization code, because the interesting code is supposed to live downstream of the auth boundary, not inside it.
Related
- Repo: https://github.com/foxck016077/apify-gmail-inbox-intel (MIT)
- If you are designing automations where authorization, retry, and alerting all need to live in one operable loop, the related toolkit page is: https://foxck.gumroad.com —
AI Automation Workflow Pack($29) is the closest match on theme.
Top comments (0)