> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up a Google Cloud OAuth App

> Create your own Google OAuth app so you can connect Gmail, Google Search Console, Google Ads, and more to Hiveku

Before you connect any Google service to Hiveku — Gmail, Search Console, Google Ads, Business Profile — you need a Google Cloud OAuth app. You create this once, register it in Hiveku, and then reuse it across every Google integration.

<Info>
  This is the BYOK (Bring Your Own Key) model. Your users see your org on the consent screen, not Hiveku's. You own the scopes and the API quota, and your data connection is routed through your own Google project.
</Info>

## Why BYOK?

* **Your brand on the consent screen.** Users see "Acme, Inc. wants to access your Gmail" rather than a generic third-party app.
* **Your scopes.** Ask for exactly what you need, nothing more.
* **Your quota.** API limits are tracked against your project, not shared with other Hiveku customers.
* **Your control.** Rotate secrets, revoke tokens, and audit usage from your own Google Cloud Console.

## Before You Start

You'll need:

* A Google account with access to [Google Cloud Console](https://console.cloud.google.com)
* Access to Hiveku as an admin so you can register the app in **Settings > OAuth Apps**

<Tip>
  If your team uses Google Workspace and only internal users will authorize the app, use an **Internal** consent screen — it skips Google's verification step for Sensitive scopes like Gmail.
</Tip>

## Create the OAuth App

<Steps>
  <Step title="Create a Google Cloud project">
    Go to [console.cloud.google.com](https://console.cloud.google.com), click the project picker in the top bar, and choose **New Project**.

    Name it something recognizable — e.g., `Acme Hiveku` — and click **Create**. Wait a few seconds for the project to provision, then select it from the picker.
  </Step>

  <Step title="Enable the APIs you'll use">
    Go to **APIs & Services > Library** and enable each API for the integrations you plan to connect. You don't have to enable everything now — you can come back later.

    * **Gmail API** — for Gmail connections
    * **Google Calendar API** — for Calendar events (bundled with Gmail)
    * **Google Search Console API** — for GSC
    * **My Business Account Management API** + **Business Profile Performance API** — for Google Business Profile
    * **Google Ads API** — for Google Ads

    Click each API, then click **Enable**.
  </Step>

  <Step title="Configure the OAuth consent screen">
    Go to **APIs & Services > OAuth consent screen**.

    Choose a **User Type**:

    * **Internal** — only users in your Google Workspace organization can authorize. Skips Google's verification review.
    * **External** — any Google account can authorize. Required if users outside your Workspace will connect. Sensitive scopes (Gmail, Drive, Calendar read/write) will trigger a verification requirement before production use.

    Fill in:

    * **App name** — shown on the consent screen
    * **User support email** — a contact for users
    * **Developer contact email** — a contact for Google
    * **App logo** (optional but recommended for branding)

    Click **Save and Continue**. On the Scopes step, you can add scopes now or leave empty — you can edit this list later.

    For **External** user type, add test users (Google accounts allowed to authorize during testing) until your app is verified.
  </Step>

  <Step title="Create an OAuth 2.0 Client ID">
    Go to **APIs & Services > Credentials > Create Credentials > OAuth client ID**.

    * **Application type:** Web application
    * **Name:** something descriptive, e.g., `Hiveku Web Client`
    * **Authorized redirect URIs:** click **Add URI** and paste exactly:

      ```
      https://app.hiveku.com/api/oauth/google/callback
      ```

    Click **Create**. A dialog shows your **Client ID** and **Client Secret** — copy both immediately.

    <Warning>
      Never commit your Client Secret to source control, share it in Slack, or expose it in logs. If it leaks, open the credential in Google Cloud Console and click **Reset Secret**.
    </Warning>
  </Step>

  <Step title="Register the app in Hiveku">
    In Hiveku, go to **Settings > OAuth Apps > Add**.

    * **Provider:** Google
    * **Name:** a label just for you, e.g., `Acme Google`
    * **Client ID:** paste from Google Cloud
    * **Client Secret:** paste from Google Cloud

    Save. The app is now available to pick from any Google integration flow.
  </Step>
</Steps>

## Verify It Works

Go to any Google integration flow — e.g., **CRM > Email Connections > Add > Gmail** — and start the connection. You should:

1. See your registered Google app in the dropdown
2. Be redirected to a Google consent screen showing **your** app name
3. After consent, land back in Hiveku with the connection saved

If any of those fail, check the troubleshooting section below.

## Security Notes

<Warning>
  Your Client Secret is equivalent to a password for your OAuth app. Anyone with it can request tokens as your app. Rotate it immediately if leaked — **Google Cloud Console > Credentials > your client > Reset Secret** — and update the new value in Hiveku.
</Warning>

* Restrict who in your org has access to the Google Cloud project
* Review the **OAuth consent screen > Test users** list periodically
* Audit usage via **APIs & Services > Dashboard** — unusual spikes are a flag

## Troubleshooting

<AccordionGroup>
  <Accordion title="redirect_uri_mismatch error during authorization">
    Google requires an exact match on the redirect URI. Open your OAuth client in **APIs & Services > Credentials** and confirm the URI is:

    ```
    https://app.hiveku.com/api/oauth/google/callback
    ```

    Common mistakes: `http://` instead of `https://`, missing `/callback`, a trailing slash, or a typo in `hiveku`.
  </Accordion>

  <Accordion title="Access blocked: this app's request is invalid">
    Usually means a scope you're requesting hasn't been added to the OAuth consent screen, or the API hasn't been enabled. Go to **APIs & Services > Library** and enable the relevant API (Gmail API, Search Console API, etc.), then try again.
  </Accordion>

  <Accordion title="Access blocked: app not verified">
    For **External** consent screens with Sensitive or Restricted scopes (Gmail, Drive, Calendar read/write), Google requires verification for production use. Two options:

    * Add the user as a **Test user** on the consent screen for testing
    * Submit your app for Google verification via the consent screen page (takes days to weeks)

    For internal-only teams, consider switching to an **Internal** consent screen, which skips verification entirely.
  </Accordion>

  <Accordion title="This app isn't verified warning for users">
    Expected during testing. Users can click **Advanced > Go to \[app name] (unsafe)** to continue. For production, submit for Google verification.
  </Accordion>

  <Accordion title="Scopes the user sees don't match what I requested">
    Each integration requests its own set of scopes. If a scope is missing, it usually means the corresponding API isn't enabled in the Google Cloud project, or the scope isn't listed on the OAuth consent screen. Enable the API under **APIs & Services > Library** and add the scope to the consent screen.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Connect Gmail" icon="envelope" href="/how-tos/connect-gmail">
    Send and read email through your Google app
  </Card>

  <Card title="Connect Google Search Console" icon="magnifying-glass" href="/how-tos/connect-gsc">
    Import SEO performance data
  </Card>

  <Card title="Connect Google Ads" icon="chart-line" href="/how-tos/connect-google-ads">
    Manage PPC campaigns
  </Card>

  <Card title="Connect Google Business Profile" icon="store" href="/how-tos/connect-gbp">
    Manage your local listings
  </Card>
</CardGroup>