Every other Google product (Google Ads, Analytics, Search Console, Business Profile, Calendar and Meet) connects in one click through Hiveku’s own Google app. It needs no Google Cloud project of yours, so skip this page for those.
Why Gmail needs your own app
Google lets an outside app read Gmail only after a yearly security review. An internal app skips that review, because only people in your own Google Workspace can sign in to it. Your app is used only for your own mailboxes, and it reads and sends mail only when a mailbox owner has approved it.Before you start
- The mailbox is in Google Workspace. A personal @gmail.com address cannot use an internal app. Use a mailbox on your Workspace domain, or connect Outlook instead.
- You sign in as someone in that Workspace who may create Google Cloud projects. In most organizations everyone may. If Google says you lack permission, ask your Google Workspace admin.
- The mailbox can sign in. A Google Group (such as a support@ group) cannot connect. Use a real user mailbox.
- You are an admin in Hiveku, so you can add the app in Settings > OAuth Apps.
Create the project
Pick how you want to work. All three ways end with the same project.- Claude Code or Codex
- Your terminal or Cloud Shell
- Browser only
With the Hiveku plugin installed, ask in plain words: “Connect our support Gmail” or “Set up Gmail for the help desk”. It reads where your account stands, then walks you through one step at a time. It runs the commands for you, and stops when a step is yours.
- Signing in. When it asks you to sign in to Google Cloud: in Claude Code, type
! gcloud auth loginin the prompt (the!runs it in your session). In Codex, rungcloud auth loginin your own terminal, then approve eachgcloudcommand Codex asks to run outside its sandbox. - The two Google pages below are yours to fill in. It gives you the links and the exact values.
- The client secret never goes through the chat. Once Google downloads the client file, Claude Code or Codex sends it to Hiveku with one command on your computer (Codex asks you to approve that command, because it uses the internet). Or upload the file yourself under Settings > OAuth Apps. Never paste the secret into the chat.
gcloud is not installed, it tells you how to install it, or you can work in Google Cloud Shell from the next tab.Finish in Google and Hiveku
No command can do these two Google pages; Google offers them only in the browser.1
Branding and audience
Open
https://console.cloud.google.com/auth/branding?project=<PROJECT_ID>. If Google says the Google Auth Platform is not configured yet, click Get started.- App name:
Hiveku(people see it when they connect a mailbox) - User support email: your own address, or a Google Group you manage
- Audience: Internal
- Contact information: your email address
2
Create the client
Open
https://console.cloud.google.com/auth/clients?project=<PROJECT_ID> and click Create client.- Application type: Web application
-
Name:
Hiveku -
Authorized redirect URIs: click Add URI and enter exactly:
3
Register the app in Hiveku
Working with Claude Code or Codex? It sends the file you downloaded to Hiveku for you, with one command on your computer, so you can skip this step.Otherwise, in Hiveku, open Settings > OAuth Apps and click New OAuth app.
- Provider: Google
- Name: a label for you, such as
Acme Gmail - Google client file (JSON): the file you downloaded. Or type the Client ID and Client Secret from Google instead.
- Allowed Products: CRM email (Gmail / Outlook)
What this creates
One Google Cloud project with the Gmail API on, an internal consent screen, and one web client. It needs no billing account. Nothing else in your Google Cloud changes.Instant replies (optional)
Hiveku checks a connected Gmail inbox for new mail every 10 minutes. With instant replies, Gmail tells Hiveku about each new email as it arrives, and it shows up within about a minute. You set it up once for your Gmail app, and every inbox on the app can use it. Set it up from Claude Code or Codex: ask “turn on instant replies for support@yourdomain.com”. It walks you through these steps and runs the commands with you:- Billing on the project. Google’s Pub/Sub, which carries Gmail’s announcements, needs a billing account on the project. Its free tier covers a support inbox’s announcements.
- A Pub/Sub topic named
hiveku-gmail-pushin your Gmail app’s own project, which Gmail is allowed to publish to. - Hiveku’s push subscription on that topic. Hiveku gives you the exact command once, with a token in it that proves the announcements are yours.
- Push turned on for the inbox, then a test email to check it arrives within a minute.
Organizations created since May 2024 only allow their own accounts into Google Cloud, and Gmail announces mail through a Google account. If Google refuses step 2, Claude Code or Codex asks you before it lifts that rule for this one project, adds Gmail’s account to the topic, and puts the rule straight back. Changing it needs the Organization Policy Administrator role; without it, your Google Workspace admin runs the same commands. If you’d rather not, replies keep arriving every 10 minutes.
Troubleshooting
Error 403: org_internal
Error 403: org_internal
The account that signed in is outside the organization that owns the app. Sign in as the mailbox, with its own Workspace account. If you set this up for a client, create the app in the client’s Workspace, signed in with their account, not yours.
Access blocked: your administrator has blocked this app (admin_policy_enforced)
Access blocked: your administrator has blocked this app (admin_policy_enforced)
Your Workspace admin limits which apps may use Google data. The admin marks the app trusted: in the Google Admin console, Security > Access and data control > API controls > Manage third-party app access, add the app by its client ID, and set it to Trusted.
Error 400: redirect_uri_mismatch
Error 400: redirect_uri_mismatch
The client’s redirect URI must be exactly
https://app.hiveku.com/api/oauth/google/callback: https, no trailing slash. The client must be a Web application; a Desktop client has no redirect URIs.Internal is greyed out, or only External is offered
Internal is greyed out, or only External is offered
The project has no organization: it was created under No organization, or by a personal Google account. Create a new project inside your organization (
--organization=<ORG_ID>, or pick your organization under Location).The connection stops working every 7 days
The connection stops working every 7 days
The app is External and in Testing, and Google ends those sign-ins after 7 days. In Google Cloud, open Audience and click Make internal, then reconnect the mailbox once.
Google shows 'This app isn't verified'
Google shows 'This app isn't verified'
The app is External. For Gmail it must be Internal: in Google Cloud, open Audience and click Make internal.
Instant replies: 'do not belong to a permitted customer'
Instant replies: 'do not belong to a permitted customer'
Your organization only allows its own accounts into Google Cloud, and Gmail’s announcements come from a Google account. See Instant replies: the fix is a project-only exception, put back right after, and only with your yes.
Instant replies are on, but mail still takes 10 minutes
Instant replies are on, but mail still takes 10 minutes
Hiveku is not receiving Gmail’s announcements: the push subscription is missing, or still uses an older token. Ask Claude Code or Codex to rotate the Gmail app’s push token and update the subscription. Mail keeps arriving every 10 minutes meanwhile.
The project id is refused
The project id is refused
Project ids are unique across all of Google Cloud and cannot contain
google or ssl. Add a few letters or digits and try again.What’s next?
Help desk email
Turn your support inbox into help desk conversations
Connect Gmail
Connect a Gmail inbox for the CRM and sales
Set up your Outlook app
The same setup for Microsoft 365
Connect Google Calendar
Calendar and Meet, in one click