# Connect Gmail

An account of Gmail is connected once, on the instance, by a person who then gives missions access to its resources; the agent never receives the credential. Experimental, classifier-only : identity-zoned risks for reading, drafting and labelling in a Gmail mailbox. No tool is executable yet.

Experimental: the gateway registers this plugin and classifies its calls, but keeps it out of the connect and mission flows and lists none of its tools to agents.

Experimental. One account is one Gmail mailbox, which is also its single resource. The plugin models the permissions of reading, drafting and labelling by who the sender or the recipient is, but it executes nothing yet: no tool is offered to agents.

Permissions, presets and tools of this service: [Gmail plugin](/plugins/gmail).

## How to connect

On the instance: Accounts → Connect an account, then pick the service. A company app, when the service needs one, is registered once by an administrator under Settings → Administration → Company apps, or set in the configuration (`providers.<id>.*`, see [configuration keys](/docs/configuration/keys)). Every instance registers its own app: this gateway never uses an app shared with another one.

### The usual way: through your company's OAuth app at the service (one click once the app is registered)

Scopes asked: `https://www.googleapis.com/auth/gmail.readonly`, `https://www.googleapis.com/auth/gmail.compose`.

## Disconnecting

Remove the application's access in the Google Account of the mailbox, under Security, in the list of third-party apps with account access.

## Registration notes from the plugin

From the plugin's [README](https://github.com/vaubaan/gateway/blob/main/plugins/gmail/README.md), written for the people who register the app or create the token.

### Credential — how the company registers its app

1. Google Cloud Console → **APIs & Services → Credentials → Create
   credentials → OAuth client ID**, type _Web application_. Enable the
   **Gmail API** on the project and configure the OAuth consent screen
   (internal user type for a Workspace organisation).
2. Authorised redirect URI: the instance callback,
   `<public_url>/connections/callback/gmail`.
3. Copy the client id and secret into the instance configuration under the
   Gmail provider app (`appConfig.client_id` / `appConfig.client_secret`).

The gateway runs the authorization-code flow declared by
`gmailCredentialSpec`: `https://accounts.google.com/o/oauth2/v2/auth` and
`https://oauth2.googleapis.com/token`, PKCE S256, `client_secret_post`,
`access_type=offline` + `prompt=consent` (a refresh token on every connect),
`include_granted_scopes=true`. Scopes are **`gmail.readonly` and
`gmail.compose` only**: no `gmail.modify` (needed upstream by the `label_*`
tools, but it also unlocks sending), no `gmail.send`. Widening them is an
incremental-authorization decision for the execution phase.

The plugin implements no provider-specific refresh: Google's refresh is the
standard `refresh_token` grant the host performs from the spec.