Social Auth

Social auth is a two-step process: you redirect the user to the provider login page, then exchange a short-lived code for a refresh token once they return.

Setup (one-time, in the dashboard)

Before using these endpoints you need to configure the OAuth provider in your project:

Go to Project Settings and add your frontend URL as the Site URL (e.g., https://myapp.com).
Go to Auth → Social Auth and select GitHub or Google.
Copy the read-only Callback URL shown by urBackend (e.g., https://api.ub.bitbros.in/api/userAuth/social/github/callback).
Register that callback URL in the provider’s OAuth app settings (GitHub: Developer Settings → OAuth Apps; Google: Cloud Console → Credentials).
Paste the provider’s Client ID and Client Secret into urBackend and enable the provider.

Step 1 — Start the OAuth Flow

Redirects the user’s browser to the provider login page. Because this is a browser redirect (not a fetch call), pass your API key as a query parameter.

string

required

OAuth provider name. Accepted values: github, google.

string

required

Your pk_live_… key. Can also be sent as a header if you are making a non-redirect request.

Response: HTTP redirect to the provider login page. The browser handles this automatically.

// Redirect the user to start the OAuth flow
window.location.href =
  'https://api.ub.bitbros.in/api/userAuth/social/github/start?x-api-key=pk_live_YOUR_KEY';

// Or for Google:
window.location.href =
  'https://api.ub.bitbros.in/api/userAuth/social/google/start?x-api-key=pk_live_YOUR_KEY';

After the user authenticates with the provider, urBackend redirects them to:

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

Param	Location	Description
`token`	URL fragment (`#`)	Access token (JWT) — use for API calls
`rtCode`	Query string	One-time code to exchange for a refresh token
`provider`	Query string	`github` or `google`
`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 token leakage through referrer headers or server logs.

Step 2 — Exchange `rtCode` for a Refresh Token

Your /auth/callback page must call this endpoint to convert the one-time rtCode into a long-lived refresh token.

rtCode is one-time use and expires in 60 seconds. Exchange it immediately when your callback page loads.

Required Headers

Header	Value
`x-api-key`	Your `pk_live_…` key
`Content-Type`	`application/json`

Request Body

string

required

The access token extracted from the URL fragment (#token=…).

string

required

The one-time exchange code from the query string (?rtCode=…).

Response Fields

boolean

true when the exchange succeeded.

object

Show data

string

The long-lived refresh token. Store this securely — use it with /api/userAuth/refresh-token to get new access tokens.

string

Human-readable status message.

Full Callback Page Example

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

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

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

      if (error) {
        console.error('OAuth error:', error);
        navigate('/login');
        return;
      }

      // Extract token from fragment, rtCode from query string
      const hashParams = new URLSearchParams(window.location.hash.slice(1));
      const accessToken = hashParams.get('token');
      const rtCode = queryParams.get('rtCode');

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

      // Exchange rtCode for refresh token
      const res = 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 { success, data } = await res.json();

      if (!success) {
        navigate('/login');
        return;
      }

      // Store tokens and proceed
      localStorage.setItem('accessToken', accessToken);
      localStorage.setItem('refreshToken', data.refreshToken);
      navigate('/dashboard');
    }

    handleCallback();
  }, [navigate]);

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

export default AuthCallback;

Success Response

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

Error Responses

{ "success": false, "data": {}, "message": "rtCode and token are required" }

{ "success": false, "data": {}, "message": "Invalid or expired refresh token exchange code" }

Overview

Authentication

Database

Storage

Mail

Setup (one-time, in the dashboard)

Step 1 — Start the OAuth Flow

Step 2 — Exchange `rtCode` for a Refresh Token

Required Headers

Request Body

Response Fields

Full Callback Page Example

Success Response

Error Responses

​Setup (one-time, in the dashboard)

​Step 1 — Start the OAuth Flow

​GET /api/userAuth/social/:provider/start

​Step 2 — Exchange rtCode for a Refresh Token

​POST /api/userAuth/social/exchange

​Required Headers

​Request Body

​Response Fields

​Full Callback Page Example

​Success Response

​Error Responses

Setup (one-time, in the dashboard)

Step 1 — Start the OAuth Flow

GET `/api/userAuth/social/:provider/start`

Step 2 — Exchange `rtCode` for a Refresh Token

POST `/api/userAuth/social/exchange`

Required Headers

Request Body

Response Fields

Full Callback Page Example

Success Response

Error Responses