connect google workspace.
For users, this is the sign-in you know from every modern app: click sign in with Google on the card, approve, done — nothing to create, nothing to configure. The steps below are for one reader only: whoever operates the macro deployment. Registering macro's own app with Google is the same one-time thing every product with that button did once, and it is never repeated per user or per customer. Steps 01–04 are the operator's, once ever; 05–06 are everyone's, every time. The operator needs a Google account that can use console.cloud.google.com, and about ten minutes.
the six steps
create the project, enable the api
At console.cloud.google.com: create a project (call it macro), then APIs & Services → Library → search Gmail API → Enable.
the consent screen
APIs & Services → OAuth consent screen. App name macro. Pick Internal if it's offered (Google Workspace organizations get it — no verification, no warnings). Otherwise pick External and add yourself under test users.
create the oauth client
Credentials → Create credentials → OAuth client ID → type Web application. Under authorized redirect URIs, add these two, character for character:
http://localhost:5179/app/api/v1/connections/c_google/oauth/callback https://macro.limited/app/api/v1/connections/c_google/oauth/callbackCopy the client ID and the client secret it gives you.
hand the client to macro — once
With macro running locally:
GOOGLE_CLIENT_ID=… GOOGLE_CLIENT_SECRET=… npm run google:appThat stores the client through macro's write-only credential store, same as every other secret: encrypted, never shown again. This is the step that turns the card's button on for everyone.
sign in
In macro: Settings → connections → the Google Workspace card → sign in with Google. You leave for Google's consent page and come straight back.
approve
The consent screen lists exactly what the card says — gmail, read-only — and nothing wider. Allow, and you land back on connections with the card connected. macro keeps the credential server-side; nobody ever sees a token.
when the sign-in bounces back
A sign-in that can't finish returns you to connections with a note saying why — the same note lands on the record.
"the platform's app credential is missing"
Steps 01–04 haven't been done yet — the button has nothing to sign in to. This is the note behind a sign-in that seems to do nothing.
google says redirect_uri_mismatch
The redirect URI in step 03 must match character for character, including the port and the path. Fix it on the OAuth client and try again.
"no durable credential was granted"
Google only hands out the long-lived credential on a first consent. Revoke macro at myaccount.google.com/permissions, then sign in again.
the connection works, then quietly stops after a week
An External app still in Testing status gets credentials Google expires after 7 days. Just sign in with Google again — the fresh sign-in fully replaces the stored credential. The weekly expiry goes away once the app is published and verified.
google warns "unverified app"
The consent screen was set to External (step 02) and the app isn't verified. As the developer that's expected: Advanced → continue. A Google Workspace organization can use Internal and never sees the warning.
how the credential is kept
The sign-in leaves macro holding a refresh token — stored encrypted, server-side, never displayed. macro exchanges it for short-lived access on its own, and only for the scopes on the card. remove credential on the card takes it out of macro; revoking at Google shuts it off at the source, and macro says which connection needs attention rather than failing quietly.