Google OAuth Integration

ButtrBase supports Google Sign-In via the standard OAuth 2.0 / OIDC flow. Users click "Continue with Google", are redirected to Google's consent screen, and land back in your app — fully authenticated.

Prerequisites

1. Google Cloud project: Open the Google Cloud Console and create or select a project. 2. OAuth consent screen: Configure the consent screen under APIs & Services → OAuth consent screen. Set the user type (External for production), fill in the required fields (app name, support email, developer contact), and add the email, profile, and openid scopes. 3. OAuth 2.0 credentials:* Under *APIs & Services → Credentials*, click *Create Credentials → OAuth client ID*. Choose **Web application**. Under *Authorised redirect URIs, add your ButtrBase callback URL: ~~~ https:///api/auth/social/callback/google ~~~ 4. Copy the Client ID* and *Client secret.

Configure in ButtrBase

Set the following environment variables on the ButtrBase backend:

| Variable | Description | |---|---| | GOOGLE_CLIENT_ID | OAuth 2.0 Client ID | | GOOGLE_CLIENT_SECRET | OAuth 2.0 Client Secret |

Or pass them as part of the /api/v1/apps/{app_uuid}/oauth-providers API:

~~~json POST /api/v1/apps/{app_uuid}/oauth-providers Authorization: Bearer

{ "provider": "google", "client_id": "1234567890-xxxx.apps.googleusercontent.com", "client_secret": "GOCSPX-xxxxxxxxxxxxxxxx" } ~~~

OAuth Flow

1. Initiate: Redirect the user to the ButtrBase social login URL: ~~~ GET /api/auth/social/initiate/google?redirect_uri=https://yourapp.com/callback ~~~ 2. Callback: ButtrBase exchanges the authorization code, verifies the ID token, and issues a session token. 3. Session: The user is provisioned (first login) or linked to an existing account. Your callback URL receives: ~~~json { "token": "", "refresh_token": "", "user_uuid": "...", "org_uuid": "..." } ~~~

Scopes Requested

ButtrBase requests the minimum scopes needed:

| Scope | Purpose | |---|---| | openid | Required for OIDC | | email | Provision account with verified email | | profile | Populate display name on first login |

Troubleshooting

redirect_uri_mismatch: The redirect URI in the Google Cloud Console must exactly match what ButtrBase sends. Include the trailing path and no trailing slash. Verify against the Authorised redirect URIs list.

Invalid client: Double-check the Client ID and Secret. Credentials from a deleted project will return this error.

Access blocked (needs verification): In development, add your test email as a Test user on the consent screen. In production, complete Google's app verification process.