DEV Community: foxck016077

Gmail OAuth client_id is not a secret â design notes for self-host Actors

foxck016077 — Sat, 16 May 2026 03:20:01 +0000

This question keeps coming up:

"My Gmail OAuth client_id got leaked. Is the system compromised?"

Short answer: client_id was never a secret. What you actually need to protect is the token, the client_secret (if your flow uses one), and the overall authorization exchange boundary.

This matters more in a self-host Actor scenario, because you are not shipping a single deployment â€” every user runs it their own way.

Public identifier, not sensitive credential

The OAuth client_id is closer to an application identifier than a password. It needs to be visible to the OAuth server and the front-end flow. In many scenarios it appears in places that are reasonable to see.

Treating client_id like a password and "hiding" it is usually a misunderstanding:

You cannot hide it (front-end, request URLs, logs all expose it)
Hiding it does not raise overall security
Worse, it can distract you from the real attack surface

The question worth asking is: if an attacker knows your client_id, what can they still do? If the answer is "nothing â€” they cannot complete an authorization exchange or obtain a valid token", your design is pointing in the right direction.

Where the security budget actually goes

For a self-host Actor, security is about flow integrity, not a single magical value. I focus on four layers:

redirect URI allowlist â€” only registered and verifiable callbacks
state / anti-CSRF â€” every authorization round-trip is bound to the originating session
token storage and rotation â€” least privilege, shortest exposure, revocable
tenant isolation â€” every token is namespaced to a tenant and never crosses boundaries

If these four layers are solid, client_id visibility is not a primary risk.

Common mistake: budget in the wrong place

I have seen projects spend real effort on "obfuscating client_id" while ignoring problems that actually cause incidents:

weak callback endpoint validation
tokens accidentally landing in logs with broad ACLs
error handlers leaking internal state to the caller
inconsistent multi-tenant key naming that lets one tenant trip into another's data

Those are the things that bite.

Security is not about mystique. It is about staying recoverable in the worst case.

What this means for multi-tenant Actor design

Once you accept "client_id is visible by design", the architecture gets cleaner. Attention naturally shifts to:

scope minimization â€” request only the permissions you truly need (in my Actor, gmail.readonly and nothing else)
explicit token lifecycle â€” when it renews, when it expires, when it can be revoked
auditable execution path â€” which tenant triggered which run when

These decisions directly affect product trust and how much firefighting future-you will be doing.

Self-host does not exempt you from threat modeling

A tempting shortcut: "It's self-host, so the risk lives with the user."

That is half right. Yes, deployment responsibility moves to the operator. But as the author you still owe secure defaults:

safe defaults rather than risky defaults
explicit documentation rather than verbal hints
observable errors rather than silent failures

Otherwise you are not reducing risk, you are just shifting it.

Documentation pattern

For OAuth-touching repos, I now write three things first:

Which values are public, which must stay private
The lifecycle and revocation path for every token
What a user can actually do when an authorization error happens

Two effects:

new users do not get blocked on a panic about the wrong thing
experienced reviewers can audit your security logic quickly

The clearer you are, the easier it is for the community to trust your project.

Open-source carries extra weight

In open source, a misleading security narrative is more dangerous than in a private product, because it gets copied.

If you frame client_id as "top secret", others will copy that posture and ship the same broken model with real problems intact.

I prefer to spell it out in the README:

client_id is expected to be visible
the real sensitive surface is token handling and flow protection
multi-tenant isolation is enforced through data structure and routing logic

That way, even a fork carries a less-wrong threat model forward.

Closing: stop asking "can I hide it"

The question I keep on a sticky note for OAuth design is:

"If this value gets seen, is the system still safe?"

If a single exposed value collapses the system, the problem is not secret management â€” it is brittle architecture.

For Gmail OAuth in a self-host Actor, client_id is not the protagonist. The real protagonist is a verifiable, revocable, isolated authorization system.

Repo: https://github.com/foxck016077/apify-gmail-inbox-intel (MIT)
If you work on long-running agents and workflow systems, the related theme â€” namespacing state, permission, and context boundaries to keep an expanding system controllable â€” is something I think about a lot. Toolkit page: https://foxck.gumroad.com

An Apify Actor for Gmail inbox analytics â refresh-token-only OAuth, async router, per-feature quota

foxck016077 — Sat, 16 May 2026 01:31:10 +0000

I just open-sourced an Apify Actor for Gmail inbox workflow analytics: apify-gmail-inbox-intel. It is not a scraper, not a bulk sender â€” it is an inbox analytics tool on gmail.readonly scope. This post is a design tour, not a tutorial.

If you have ever asked "which client thread did I forget to reply to?" or "what is my average reply turnaround?", this is the kind of workflow it covers.

Why an Apify Actor

I needed three things at once: serverless runtime, pay-per-result billing, and a real input schema. Apify gives me all of them without writing a backend. I get a hosted endpoint, dataset storage, a key-value store for state, and a developer audience that is already paying for actors.

The actor exposes four features through a single entrypoint:

thread_search â€” query Gmail threads by q, paginate, return metadata + message counts
reply_metrics â€” for each thread, compute reply-from-me, reply-from-others, last-reply age, SLA breach flag
summarizer â€” optional OpenAI LLM thread summary (BYO API key)
unread_digest â€” list unread threads in the last N hours, grouped by label

Design decision 1: refresh-token-only OAuth

The hardest call early on was OAuth. Two paths:

3-legged OAuth on the Actor side â€” Actor hosts callback URL, exchanges code, stores tokens.
Refresh-token-only â€” user does the OAuth dance once on their own, hands me {refresh_token, client_id, client_secret} as Actor input.

I picked option 2. Reasons:

Apify Actors do not have a stable HTTPS callback URL per user. Each run is a job, not a server.
"We never store your Gmail tokens" is a far easier privacy story to defend.
I do not want to be the holder-of-secrets for someone else's mailbox.

In the Actor, the flow is:

# src/gmail_client.py â€” sketch
async def get_access_token(oauth_token: dict) -> str:
    resp = await httpx_client.post(
        "https://oauth2.googleapis.com/token",
        data={
            "grant_type": "refresh_token",
            "refresh_token": oauth_token["refresh_token"],
            "client_id": oauth_token["client_id"],
            "client_secret": oauth_token["client_secret"],
        },
    )
    return resp.json()["access_token"]

Access token lives in memory only. Job end â†’ process tears down â†’ token gone. Best effort, but at least nothing persists in Apify storage with my code path.

Design decision 2: one async router, not four actors

Tempting to split into four actors. I did not, for two reasons:

Marketing surface area. One actor with four feature enum values gets one Store page, one rating, one review pile. Four actors split everything four ways.
Shared OAuth + shared quota. The token exchange, error handling, mask helpers, KVS quota â€” all reusable.

src/main.py is just a router:

FEATURES = {
    "thread_search": thread_search.run,
    "reply_metrics": reply_metrics.run,
    "summarizer": summarizer.run,
    "unread_digest": digest.run,
}

async def main():
    actor_input = await Actor.get_input() or {}
    feature = actor_input.get("feature")
    if feature not in FEATURES:
        raise ValueError(f"Unknown feature: {feature}")
    await FEATURES[feature](actor_input)

Each feature module owns its own INPUT_SCHEMA.json semantics through the same shared file â€” the feature enum drives validation downstream in each handler.

Design decision 3: quota lives in Apify KVS

Free tier is 100 threads / month. That counter has to survive across runs. Apify KeyValueStore is the obvious home â€” no extra DB, persistent, scoped to the Actor.

# src/quota.py â€” sketch
async def check_and_increment(user_id: str, feature: str, n: int):
    kvs = await Actor.open_key_value_store()
    key = f"quota/{user_id}/{month_key()}/{feature}"
    used = (await kvs.get_value(key)) or 0
    if used + n > FREE_LIMIT:
        raise QuotaExceeded(feature, used, FREE_LIMIT)
    await kvs.set_value(key, used + n)

Month roll-over is a string key by year-month â€” no cron, no migration, no drift. Pro tier flips a flag and skips the check entirely.

Tests

Six pytest tests, asyncio_mode = auto in pytest.ini. Coverage:

Router rejects unknown feature
Each of 4 features short-circuits cleanly in dry_run=True
Quota raises after limit, allows under

[pytest]
asyncio_mode = auto

That tiny config line is the difference between "6 tests pass" and "6 tests error: missing event loop". Learned it the hard way.

Pricing model

Free: 100 threads / month
Pro: $19 / month (5000 threads metadata + 100 LLM summaries)
Pay-per-result add-on: $0.50 / 1,000 thread metadata, $0.005 / summary

Apify handles billing. I handle code.

What I would do differently

Webhook trigger â€” right now unread_digest runs on demand. A scheduled trigger + Slack/Discord delivery is the obvious next product.
Label-level rules â€” reply_metrics is global. A per-label SLA matrix would be more useful for sales teams.
Multi-account fan-out â€” one run, multiple OAuth tokens, one combined dataset.

Code

Repo: https://github.com/foxck016077/apify-gmail-inbox-intel
License: MIT
Actor manifest: .actor/actor.json + INPUT_SCHEMA.json if you want to fork

If you build automation workflows alongside this kind of inbox tooling, I keep a small Gumroad with practical n8n templates (lead auto-responder, content pipeline, competitor monitor): https://foxck.gumroad.com. Not required, just adjacent.

Happy to take feedback on the OAuth-only design â€” was there a reason to go full 3-legged that I am missing?