Social Auth

urBackend supports OAuth sign-in via GitHub and Google. Once configured, your users can authenticate without creating a password — urBackend creates or links their account automatically. Base URL: https://api.ub.bitbros.in

How the flow works

Your app  →  urBackend /start  →  GitHub / Google  →  urBackend /callback
                                                              ↓
Your app (/auth/callback)  ←  urBackend redirects with tokens

After a successful login, urBackend redirects the user to <your-site>/auth/callback with an access token in the URL fragment and a short-lived exchange code in the query string.

Dashboard setup (one time)

Set your site URL

Go to Project Settings in the urBackend dashboard and enter your frontend URL (e.g., https://myapp.com). urBackend uses this as the base for the post-login redirect.

Open Social Auth settings

Go to Auth → Social Auth and select the provider you want to configure (GitHub or Google).

Copy the callback URL

urBackend displays a read-only callback URL for the selected provider:

https://api.ub.bitbros.in/api/userAuth/social/github/callback

Copy this URL — you will register it with the provider in the next step.

Paste the callback URL into the provider’s developer console:

GitHub: Settings → Developer settings → OAuth Apps → New OAuth App
Google: Google Cloud Console → APIs & Services → Credentials → Create OAuth Client

Paste credentials and enable

Copy the Client ID and Client Secret from the provider console, paste them into the urBackend Social Auth form, and toggle the provider on.

Frontend implementation

When a user clicks “Login with GitHub” or “Login with Google”, redirect their browser to urBackend’s start endpoint. Pass your publishable key as a query parameter (since this is a browser redirect, not a fetch call).

// components/LoginButtons.jsx
const API_KEY = 'pk_live_YOUR_KEY';
const API_URL = 'https://api.ub.bitbros.in';

function LoginButtons() {
  const handleGitHubLogin = () => {
    window.location.href = `${API_URL}/api/userAuth/social/github/start?x-api-key=${API_KEY}`;
  };

  const handleGoogleLogin = () => {
    window.location.href = `${API_URL}/api/userAuth/social/google/start?x-api-key=${API_KEY}`;
  };

  return (
    <div>
      <button onClick={handleGitHubLogin}>Login with GitHub</button>
      <button onClick={handleGoogleLogin}>Login with Google</button>
    </div>
  );
}

2. Create the callback page

You must create a page at /auth/callback in your frontend. After the provider login completes, urBackend redirects the user here with tokens in the URL. The callback page should:

Check for an error in the query string
Extract token from the URL fragment and rtCode from the query string
Exchange rtCode for a refresh token by calling /api/userAuth/social/exchange
Store the tokens and redirect to your app

// pages/AuthCallback.jsx
import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';

function AuthCallback() {
  const navigate = useNavigate();

  useEffect(() => {
    async function handleCallback() {
      // Check for errors
      const queryParams = new URLSearchParams(window.location.search);
      const error = queryParams.get('error');

      if (error) {
        alert('Login failed: ' + error);
        navigate('/login');
        return;
      }

      // Extract tokens from URL
      const hashParams = new URLSearchParams(window.location.hash.slice(1));
      const accessToken = hashParams.get('token');
      const rtCode = queryParams.get('rtCode');

      if (!accessToken || !rtCode) {
        alert('Missing tokens');
        navigate('/login');
        return;
      }

      // Exchange rtCode for a refresh token
      const response = await fetch('https://api.ub.bitbros.in/api/userAuth/social/exchange', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': 'pk_live_YOUR_KEY'
        },
        body: JSON.stringify({ token: accessToken, rtCode })
      });

      const data = await response.json();

      if (!data.success) {
        alert('Token exchange failed');
        navigate('/login');
        return;
      }

      // Store tokens and continue
      localStorage.setItem('accessToken', accessToken);
      localStorage.setItem('refreshToken', data.data.refreshToken);

      // Optional: store provider metadata
      localStorage.setItem('provider', queryParams.get('provider'));
      localStorage.setItem('userId', queryParams.get('userId'));

      navigate('/dashboard');
    }

    handleCallback();
  }, [navigate]);

  return <div>Completing login...</div>;
}

export default AuthCallback;

What urBackend sends to your callback URL

After a successful provider login, urBackend redirects to:

https://your-site.com/auth/callback?rtCode=abc&provider=github&projectId=p1&userId=u1&isNewUser=false&linkedByEmail=true#token=eyJ...

Parameter	Location	Description
`token`	URL fragment (`#`)	Access token (JWT) for API calls
`rtCode`	Query string	One-time code to exchange for a refresh token
`provider`	Query string	`github` or `google`
`projectId`	Query string	Your urBackend project ID
`userId`	Query string	The user’s ID in your database
`isNewUser`	Query string	`true` if the account was just created
`linkedByEmail`	Query string	`true` if an existing account was linked by email
`error`	Query string	Error message (only present on failure)

The access token is placed in the URL fragment (#) intentionally. Fragments are never sent to servers in HTTP requests, which prevents the token from leaking through referrer headers or server logs.

Exchange endpoint

Endpoint: POST /api/userAuth/social/exchange Headers:

{
  "Content-Type": "application/json",
  "x-api-key": "pk_live_YOUR_KEY"
}

Request body:

{
  "token": "eyJ... (access token from URL fragment)",
  "rtCode": "abc123 (one-time code from query string)"
}

Success response:

{
  "success": true,
  "data": {
    "refreshToken": "REFRESH_TOKEN_VALUE"
  },
  "message": "Refresh token exchanged successfully"
}

rtCode expires after 60 seconds and is one-time use. Exchange it immediately after the redirect. If it has expired or been used, you will receive "Invalid or expired refresh token exchange code" and the user will need to log in again.

Complete flow summary

Step	What happens	Who does it
1	User clicks “Login with GitHub”	Your frontend
2	Browser redirects to `/api/userAuth/social/github/start`	Your frontend
3	urBackend redirects to GitHub login page	urBackend
4	User logs in on GitHub	User
5	GitHub redirects to urBackend callback	GitHub
6	urBackend creates or links the user, generates tokens	urBackend
7	urBackend redirects to `<your-site>/auth/callback?rtCode=...#token=...`	urBackend
8	Callback page extracts `token` and `rtCode` from URL	Your frontend
9	Callback page calls `/api/userAuth/social/exchange` with both	Your frontend
10	urBackend returns `refreshToken`	urBackend
11	App stores tokens and redirects to dashboard	Your frontend

Account linking

If a user signs in with a social provider and their provider account has a verified email that matches an existing urBackend user, the accounts are automatically linked. The linkedByEmail parameter in the callback URL will be true in this case. New users created via social auth receive an internally generated hashed password to satisfy the users collection contract. They can set a real password later using the change-password endpoint.

Get Started

Core Concepts

Guides

TypeScript SDK

React SDK

Security & Limits

How the flow works

Dashboard setup (one time)

Frontend implementation

2. Create the callback page

What urBackend sends to your callback URL

Exchange endpoint

Complete flow summary

Account linking

​How the flow works

​Dashboard setup (one time)

​Frontend implementation

​1. Add login buttons

​2. Create the callback page

​What urBackend sends to your callback URL

​Exchange endpoint

​Complete flow summary

​Account linking

How the flow works

Dashboard setup (one time)

Frontend implementation

1. Add login buttons

2. Create the callback page

What urBackend sends to your callback URL

Exchange endpoint

Complete flow summary

Account linking