Social OAuth

Social OAuth lets users sign in with accounts they already have — Google, GitHub, Apple, and others. This reduces friction, eliminates another password to remember, and increases sign-up conversion rates.

Banata Auth supports 10 social OAuth providers out of the box.

Supported Providers

Setting Up a Provider

The setup is the same for every provider:

1. Create an OAuth app on the provider's developer portal.
2. Set the callback URL to the Banata auth domain that owns the provider callback.
3. Copy the Client ID and Client Secret.
4. Add the credentials to the Banata dashboard or your Convex environment.

For managed Banata projects, Banata owns the provider callback and then hands the session back to your app afterward. Your in-app callbackURL such as /dashboard or /auth/callback is a separate post-login destination.

If you self-host Banata, the provider callback belongs on your own auth deployment instead.

Callback URL Pattern

Managed Banata projects use the Banata auth domain for all provider callbacks:

https://auth.banata.dev/api/auth/callback/github          ← Managed Banata
https://auth.yourcompany.com/api/auth/callback/github     ← Custom Banata auth domain

If you self-host Banata, the callback is on your own auth/app domain instead:

http://localhost:3000/api/auth/callback/github     ← Self-hosted development
https://myapp.com/api/auth/callback/github         ← Self-hosted production

Adding Credentials via Dashboard

1. Go to Authentication > Providers in your project.
2. Select the provider you want to configure.
3. Enter the Client ID and Client Secret.
4. Save.

Adding Credentials via Convex Environment

For self-hosted setups, set the credentials on your Convex deployment:

npx convex env set GITHUB_CLIENT_ID "your-client-id"
npx convex env set GITHUB_CLIENT_SECRET "your-client-secret"

Provider Setup Guides

Google

1. Go to Google Cloud Console > Credentials.
2. Create a new OAuth client ID (Web application type).
3. Add authorized redirect URI: https://auth.banata.dev/api/auth/callback/google
4. Copy the Client ID and Client Secret.

If you use a custom Banata auth domain, register that domain instead. If you self-host Banata, use your own app/auth domain callback.

GitHub

1. Go to GitHub Developer Settings > OAuth Apps.
2. Click New OAuth App.
3. Set Homepage URL to your app URL, for example http://localhost:3000.
4. Set Authorization callback URL to https://auth.banata.dev/api/auth/callback/github.
5. Copy the Client ID and generate a Client Secret.

Apple

1. Go to Apple Developer Portal.
2. Create an App ID with Sign in with Apple enabled.
3. Create a Services ID (this is your clientId).
4. Configure the redirect URL: https://auth.banata.dev/api/auth/callback/apple
5. Create a Key with Sign in with Apple enabled and generate the client secret.

Important: Apple client secrets expire after 6 months and need periodic regeneration.

Microsoft (Azure AD)

1. Go to Azure Portal > App registrations.
2. Click New registration.
3. Set redirect URI to https://auth.banata.dev/api/auth/callback/microsoft (Web platform).
4. Note the Application (client) ID and Directory (tenant) ID.
5. Create a new client secret under Certificates & secrets.

Microsoft requires a tenantId. Options:

Facebook

1. Go to Meta for Developers.
2. Create a new app (Consumer type).
3. Add Facebook Login and set the redirect URI: https://auth.banata.dev/api/auth/callback/facebook

Twitter (X)

1. Go to the Twitter Developer Portal.
2. Create a new project and app with OAuth 2.0 enabled.
3. Set callback URL: https://auth.banata.dev/api/auth/callback/twitter

Discord

1. Go to the Discord Developer Portal.
2. Create a new application.
3. Go to OAuth2 and add redirect: https://auth.banata.dev/api/auth/callback/discord

Spotify, Twitch, LinkedIn

Follow the same pattern on each provider's developer portal:

• Spotify Dashboard
• Twitch Developer Console
• LinkedIn Developer Portal

Client-Side Usage

Initiating Social Sign-In

import { authClient } from "@/lib/auth-client";
 
await authClient.signIn.social({
  provider: "github",
  callbackURL: "/dashboard",
});

callbackURL here is where your app should land after Banata finishes the auth flow. It is not the provider callback URL you register in GitHub or Google.

This redirects the user to the provider's OAuth consent page. After they grant permission, the provider sends the user back to Banata's callback URL, Banata finalizes the session, and then redirects the browser to the callbackURL you specified.

Using the SocialButtons Component

import { SocialButtons, SignInForm } from "@banata-auth/react";
import { authClient } from "@/lib/auth-client";
 
const providers = [
  { id: "google", label: "Google" },
  { id: "github", label: "GitHub" },
];
 
export default function SignInPage() {
  return (
    <div>
      <SocialButtons
        providers={providers}
        authClient={authClient}
        callbackURL="/dashboard"
      />
      <div>or</div>
      <SignInForm authClient={authClient} callbackURL="/dashboard" />
    </div>
  );
}

How the OAuth Flow Works

Here's what happens when a user clicks "Sign in with GitHub":

1. Browser → POST /api/auth/sign-in/social { provider: "github" }
2. Your app → proxies to Banata backend
3. Banata → returns redirect to GitHub OAuth consent page
4. Browser → redirected to github.com/login/oauth/authorize
5. User → grants permission on GitHub
6. GitHub → redirects to https://auth.banata.dev/api/auth/callback/github?code=xxx
7. Banata → exchanges code for tokens, creates/links user, creates session
8. Banata → hands the session back to your app
9. Browser → redirected to your callbackURL with session cookie set

Account Linking

For managed Banata projects, the provider callback registered in GitHub or Google is on your Banata auth domain, for example https://auth.banata.dev/api/auth/callback/{provider}. The callbackURL in authClient.signIn.social(...) is only the page Banata redirects to after the auth flow is finished.

When a user signs in with a social provider and their email matches an existing account:

• Auto-link — if the email is verified on both sides, the social account is linked to the existing user.
• New account — if no user exists with that email, a new user is created.

After linking, the user can sign in with either method (email/password or social).

Troubleshooting

"redirect_uri_mismatch" error

The callback URL in your provider settings doesn't match the actual URL. Make sure it's exactly:

• Managed Banata: https://auth.banata.dev/api/auth/callback/{provider}
• Custom Banata auth domain: https://auth.yourcompany.com/api/auth/callback/{provider}
• Self-hosted Banata: https://your-domain.com/api/auth/callback/{provider}

Do not register /dashboard, /auth/callback, or any other post-login page as the provider callback. Those belong in your app's callbackURL option instead.

"Access Denied" after granting permission

• Verify the Client Secret is correctly set.
• Check that the provider is configured in your Banata project.
• For Microsoft, make sure tenantId is set.

User created without name or email

Some providers don't return all user fields by default. Check the provider's scope settings to ensure you're requesting the right permissions.

Next Steps

• Magic Links — Passwordless authentication via email
• Multi-Factor Auth — Add TOTP as a second factor
• Organizations — Multi-tenant workspaces