oauth-setup

OAuth setup

Use the oauth_authorize tool — NEVER hand-roll an http listener in bash. It opens a one-shot loopback listener on a free port (no EADDRINUSE, no port juggling), captures the code, and seals the tokens into the credential store.

The two mistakes to avoid (they cost a whole session once)

1. Use a Desktop-app OAuth client, not a Web client. In Google Cloud Console → Credentials → Create OAuth client ID → Application type: Desktop app. Desktop clients accept ANY http://127.0.0.1:<port> loopback redirect with no redirect-URI registration. A Web client requires the exact redirect URI pre-registered, which is what causes redirect_uri_mismatch.
2. Use the real scope. Gmail send is https://www.googleapis.com/auth/gmail.send (NOT https://gmail.com/..., which doesn't exist). Add openid https://www.googleapis.com/auth/userinfo.email if you want the account address auto-filled.

Flow

1. Ask the operator to create a Desktop-app OAuth client (Gmail API enabled, consent screen in Testing with themselves as a test user) and paste the client id + secret.
2. Start the flow:

   oauth_authorize({
     action: "start",
     provider: "google-gmail",
     authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
     tokenEndpoint: "https://oauth2.googleapis.com/token",
     userInfoEndpoint: "https://www.googleapis.com/oauth2/v3/userinfo",
     clientId: "<id>", clientSecret: "<secret>",
     scopes: ["https://www.googleapis.com/auth/gmail.send", "openid", "https://www.googleapis.com/auth/userinfo.email"],
     extraAuthParams: { access_type: "offline", prompt: "consent" }
   })
   

   access_type=offline + prompt=consent are required for a refresh token (otherwise re-auth is needed when the access token expires).
3. Send the operator the returned authUrl to click.
4. Await the redirect — it exchanges the code and seals the tokens:

   oauth_authorize({ action: "await", flowId: "<flowId from start>" })
   

   If it returns status pending, the operator hasn't clicked yet — tell them, then call await again.