What actually happens when you give an AI agent access to your Gmail

Every agent demo shows the same thing. Someone types "check my email and summarise anything urgent", and the agent does it. It looks like two minutes of setup. The real path is longer, and the extra length is almost entirely OAuth. Here is what is in there, step by step, because people underestimate it consistently and then blame themselves when it takes an afternoon.

Your agent needs its own OAuth application

Your agent cannot simply ask Google for your mail. It needs a registered OAuth client. That means opening the Google Cloud console, creating a project, enabling the Gmail API, and configuring a consent screen.

Gmail's sensitive scopes trigger Google's verification

The consent screen is where most people stall. Gmail's read and send scopes are classed as sensitive, so Google wants to know what your application does and who uses it. If you are one person automating your own inbox, you are in an awkward category. That flow is designed for companies shipping products to users.

The usual workaround is to leave the app in testing mode and add yourself as a test user. It works. It also shortens the refresh-token lifetime considerably, which is why so many people find their agent quietly stops reading email about a week after setup.

Choose the narrowest scope that does the job

Scope selection is a real decision. The instinct is to grant full mailbox access because it is simpler. But an agent with a send scope can send mail as you, to anyone, and an agent running on a schedule without supervision is exactly the case where the narrowest workable permission matters.

A reasonable default is read-only to start, adding send later once you have watched its behaviour for a week. You can widen a scope. You cannot un-send.

The client secret has to live somewhere your agent can read

You now hold a client secret, and it needs to sit somewhere your agent can reach. Which means it sits on a machine running a model that executes code and installs its own dependencies.

Worth deciding deliberately. A secret in a plaintext config file that any skill can read is a different risk profile from one in an environment variable, which is different again from a token your agent never holds at all. None is wrong, but the choice is easier to make up front than to discover later.

Refresh tokens fail quietly

Access tokens are short-lived and refresh tokens get you new ones, so something has to run that exchange and handle its failures.

Failures are not rare. Tokens get revoked when you change your password, when a provider updates its policy, when a testing-mode app hits its expiry window, when a scope changes. The failure mode is silent: the agent does not crash, it just starts returning nothing, and you notice four days later.

The per-service cost does not drop with practice

Everything above was Gmail. Calendar is a separate consent flow. Slack has its own app model and token types. Instagram's Graph permissions are their own experience. Notion is comparatively pleasant.

Each one is roughly the same work with a different console layout.

Three honest ways to handle it

Do it yourself. For one or two services, especially those using a simple API key rather than full OAuth, this is fine and you keep total control. Your own keys, every line reviewed, no third party. If that matters more to you than the time, stop here.

Use a community skill. Someone has likely written one. You usually still register the OAuth application yourself; the skill handles the API calls afterwards. Free, and the source is readable. Review it as you would any dependency that can reach your accounts.

Use a managed layer. Composio, Membrane, ClawLink and others handle registration, storage and refresh so you click through a hosted flow instead. You are trading credential custody for time, so read how each one stores tokens and whether you can self-host. Composio is the most complete option if you are building a product for other people to use. ClawLink, which is ours, targets the narrower case of one person running their own agent; see ClawHub or ClawLink: when to use each for where it does and does not fit.

Count your services before you pick a route

At one service, doing it by hand is faster than evaluating tools. At six, you will spend more time on token maintenance than on whatever you built the agent for, and it arrives gradually enough that you will not notice you have started.