Skip to main content
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)

1

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.
2

Open Social Auth settings

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

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.
4

Register the callback URL with the provider

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
5

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

​
1. Add login buttons

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:
  1. Check for an error in the query string
  2. Extract token from the URL fragment and rtCode from the query string
  3. Exchange rtCode for a refresh token by calling /api/userAuth/social/exchange
  4. 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...
ParameterLocationDescription
tokenURL fragment (#)Access token (JWT) for API calls
rtCodeQuery stringOne-time code to exchange for a refresh token
providerQuery stringgithub or google
projectIdQuery stringYour urBackend project ID
userIdQuery stringThe user’s ID in your database
isNewUserQuery stringtrue if the account was just created
linkedByEmailQuery stringtrue if an existing account was linked by email
errorQuery stringError 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

StepWhat happensWho does it
1User clicks “Login with GitHub”Your frontend
2Browser redirects to /api/userAuth/social/github/startYour frontend
3urBackend redirects to GitHub login pageurBackend
4User logs in on GitHubUser
5GitHub redirects to urBackend callbackGitHub
6urBackend creates or links the user, generates tokensurBackend
7urBackend redirects to <your-site>/auth/callback?rtCode=...#token=...urBackend
8Callback page extracts token and rtCode from URLYour frontend
9Callback page calls /api/userAuth/social/exchange with bothYour frontend
10urBackend returns refreshTokenurBackend
11App stores tokens and redirects to dashboardYour 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.