Auth

Google sign-in (OAuth)

Let users of your product (web, mobile, or internal tool) sign in with their Google account. This guide applies to any application wired to Kuunda Auth — not only a migration scenario.

1. How the flow works

Google does not talk to your frontend directly. Kuunda Auth sits in the middle: it receives the Google callback, creates or looks up the user, then sends the session back to your application.

1. The user clicks Continue with Google in your app.
2. The browser is redirected to Kuunda Auth (/auth/v1/authorize).
3. Kuunda Auth redirects to Google (consent screen).
4. Google calls Kuunda Auth back at theredirect URI (callback).
5. Kuunda Auth redirects to your Site URL / redirectTo with a session (fragment #access_token=…).

When it completes, the user exists under Auth → Users and your app can call the API (REST, Storage, and so on) with the JWT.

2. The three URLs (do not mix them up)

Most mistakes come from mixing these addresses. They do not play the same role.

3. Create the Google OAuth client

You can create a new client, or reuse an existing client (another backend, previous stack, internal tool): add the Kuunda URI to the redirect list, alongside URIs already there, until cutover is complete.

1. Open Google Cloud → Credentials.
2. Create (or open) a Web application client — not Android, iOS, or Desktop app.
3. Give it a readable name (e.g. Kuunda — My app).
4. Under Authorized redirect URIs, add exactly:

   https://api.kuunda-cloud.com/auth/v1/callback

   If the project uses dedicated Auth (Enterprise plan), the URI may be:

   https://{ref}.kuunda-cloud.com/auth/v1/callback

5. Under Authorized JavaScript origins, add at least:
   • https://api.kuunda-cloud.com — shared Auth
   • https://app.kuunda-cloud.com — the Test button in the console
   • https://{ref}.kuunda-cloud.com — API via the project subdomain
   • Your frontend origin: https://app.exemple.ci, and http://localhost:3000 locally
6. Save, then copy the Client ID and the Client secret.

The Google consent screen (branding, domains, test users in Testing mode) must be published, or in development your Google account must be listed as a test user.

4. Configure the Kuunda project

In the console: https://app.kuunda-cloud.com → your project → Auth → Providers.

Project URLs

On the Site URL / redirects card:

• Site URL — origin that will receive the session after login. Examples: http://localhost:3000/, https://app.exemple.ci/, or https://app.kuunda-cloud.com/ to test from the dashboard.
• Redirect URLs — every origin you will pass as redirectTo (one per line). Include localhost and production.

Enable Google

1. Expand the Google card.
2. Check Enable Google.
3. Paste the Client ID and the Client secret.
4. Check the redirect URIalert: the same value must be listed in Google Cloud.
5. Save — the badge switches to Enabled.

5. Test

1. Open a private browsing window (avoids a Google account already linked by mistake).
2. In the Kuunda console, use the Test button on the Google card — or start the flow from your app (next section).
3. Choose a Google account and accept the permissions.
4. You should land on the Site URL with a #access_token=… fragment (and usually refresh_token).
5. Under Auth → Users, the user appears (Google email, identity custom:proj-{ref}-google).

6. Integrate in your application

Use the @kuunda/kuunda-jsSDK. Project URL and anonkey: Settings → API in the console. Never expose the service_role key in the browser.

Initialize the client

import { createClient } from '@kuunda/kuunda-js';

const kuunda = createClient(
  'https://{ref}.kuunda-cloud.com',
  'kuunda_anon_…',
  { projectRef: '{ref}' }
);

“Continue with Google” button

await kuunda.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'https://app.exemple.ci/auth/callback',
  },
});

In the browser, this method redirects immediately to Kuunda Auth. redirectTo must be listed in the project’s Redirect URLs. projectRef is required so that provider: 'google' is rewritten to the project’s provider.

Provider name (SDK vs HTTP)

Kuunda Auth reserves google, github, facebook, apple, azure, x. Kuunda therefore registers a custom provider per project, using hyphens (identifier without underscores).

Without the SDK (HTTP)

Equivalent (project subdomain — apikey is optional on that host; recommended elsewhere):

https://{ref}.kuunda-cloud.com/auth/v1/authorize?provider=google&redirect_to=https%3A%2F%2Fapp.exemple.ci%2Fauth%2Fcallback

Explicit form, always valid: provider=custom:proj-{ref}-google&apikey=kuunda_anon_…

After the redirect back

Kuunda Auth returns the session in the URL fragment (#access_token=…&refresh_token=…). On the destination page:

• Read kuunda.auth.getSession() if you already persisted a session, or rebuild it from the hash then setSession.
• Clear the hash from the address bar (avoids leaking the token into history or analytics).
• Calls to kuunda.from(…) then go out with the JWT; RLS applies to the Google user.

7. Production checklist

• Google OAuth client type Web application, consent screen in production (not “Testing”).
• Kuunda callback URI registered exactly (copy-paste from the console, no trailing slash).
• JS origins: production domain + https://api.kuunda-cloud.com; drop localhost if you no longer need it.
• Site URL and Redirect URLs in Kuunda point at production HTTPS.
• anon key only in the frontend; Google client secret only in the Kuunda console.
• If you already had another callback (previous host, other BaaS), keep it until cutover is validated, then remove it.

8. Troubleshooting

Next

• Developer documentation — API keys, first SELECT, Auth / Storage / Realtime.
• Kuunda Cloud Managed — Management API, PAT, agents, and CI.
• Data import — if you are cutting over an existing stack (SQL, Auth, files).