@sooapps/sooauth-react

React SDK for SooAuth hosted authentication.

Use this package when your React app should send users to SooAuth hosted sign-in/sign-up pages, receive the callback code, exchange it for tokens, and expose the signed-in user through React hooks/components.

Links

• Console: https://sooauth.com/dashboard
• Hosted auth: https://sooauth.com/sign-in
• API issuer: https://api.sooauth.com
• Docs: https://sooauth.com/docs
• GitHub: https://github.com/sooapps/sooauth-react

Install

npm install @sooapps/sooauth-react

pnpm add @sooapps/sooauth-react

Example App

This repository includes a public Vite example:

cd examples/vite
npm install
cp .env.example .env
npm run dev

Before running it, create a SooAuth application and set:

Redirect URL: http://localhost:5173/auth/callback
Allowed origin: http://localhost:5173

Then put your application client ID in .env:

VITE_SOOAUTH_CLIENT_ID=app_xxx

Configure Your SooAuth Application

Open the SooAuth console:

https://sooauth.com/dashboard

Create or open an application, then set these values:

Applications -> Manage -> Settings

Redirect URL: https://yourapp.com/auth/callback
Allowed origin: https://yourapp.com

Redirect URL is your frontend callback route. It is not your backend API URL.

Wrap Your React App

import { SooAuthProvider } from "@sooapps/sooauth-react";

export function Root() {
  return (
    <SooAuthProvider
      clientId="app_xxx"
      redirectUri="https://yourapp.com/auth/callback"
      apiUrl="https://api.sooauth.com"
      hostedUrl="https://sooauth.com"
    >
      <App />
    </SooAuthProvider>
  );
}

Add Sign In And Sign Up Buttons

import { SignedIn, SignedOut, UserButton, useAuth } from "@sooapps/sooauth-react";

export function AuthButtons() {
  const { signIn, signUp } = useAuth();

  return (
    <>
      <SignedOut>
        <button onClick={() => signIn.redirect()}>Sign in</button>
        <button onClick={() => signUp.redirect()}>Sign up</button>
      </SignedOut>

      <SignedIn>
        <UserButton />
      </SignedIn>
    </>
  );
}

Add The Hosted Callback Route

Create a frontend route at the same URL you configured as the Redirect URL.

For example:

https://yourapp.com/auth/callback

Then call handleRedirectCallback().

import { useEffect } from "react";
import { useAuth } from "@sooapps/sooauth-react";

export function AuthCallback() {
  const { handleRedirectCallback } = useAuth();

  useEffect(() => {
    handleRedirectCallback().then(() => {
      window.location.assign("/");
    });
  }, [handleRedirectCallback]);

  return <main>Completing sign in...</main>;
}

Call Your Backend With The Access Token

import { useAuth } from "@sooapps/sooauth-react";

export function LoadPrivateDataButton() {
  const { getAccessToken } = useAuth();

  async function loadPrivateData() {
    const token = getAccessToken();

    const res = await fetch("https://api.yourapp.com/private", {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });

    return res.json();
  }

  return <button onClick={loadPrivateData}>Load private data</button>;
}

Your backend should verify the JWT audience against the SooAuth application client ID.

Email And Password

Hosted sign-in is the recommended flow.

If you want embedded email/password forms:

import { useAuth } from "@sooapps/sooauth-react";

export function LoginForm() {
  const { signIn, signUp } = useAuth();

  async function login(email: string, password: string) {
    await signIn.email(email, password);
  }

  async function register(email: string, password: string, name?: string) {
    await signUp.email(email, password, name);
  }
}

Forgot And Reset Password

import { useAuth } from "@sooapps/sooauth-react";

export function PasswordResetForm() {
  const { forgotPassword, resetPassword } = useAuth();

  async function requestReset(email: string) {
    await forgotPassword(email, "https://yourapp.com/reset-password");
  }

  async function completeReset(token: string, newPassword: string) {
    await resetPassword(token, newPassword);
  }
}

Google OAuth

Enable Google OAuth in the SooAuth console:

Applications -> Manage -> Auth methods

Then use the normal hosted redirect:

import { useAuth } from "@sooapps/sooauth-react";

export function GoogleButton() {
  const { signIn } = useAuth();
  return <button onClick={() => signIn.redirect()}>Continue with Google</button>;
}

The hosted sign-in page shows Google automatically when it is enabled for the application.

AI Agent Prompt

Paste this into an AI coding agent inside the app you want to connect:

Integrate SooAuth into this React project.

Use these values:
- Client ID: app_xxx
- API URL: https://api.sooauth.com
- Hosted auth URL: https://sooauth.com
- Redirect URI: https://yourapp.com/auth/callback

Tasks:
1. Install @sooapps/sooauth-react.
2. Wrap the React app with SooAuthProvider.
3. Add an /auth/callback route that calls handleRedirectCallback().
4. Replace local sign-in/sign-up buttons with signIn.redirect() and signUp.redirect().
5. Use getAccessToken() for protected backend requests.
6. Show SignedIn and SignedOut UI states.
7. Do not replace existing business logic; only gate protected UI/actions behind SooAuth.
8. Validate by signing in, calling a protected endpoint, signing out, and refreshing the page.

Public API

const {
  user,
  isLoaded,
  isSignedIn,
  signIn,
  signUp,
  signOut,
  refresh,
  forgotPassword,
  resetPassword,
  handleRedirectCallback,
  getAccessToken,
} = useAuth();

Components:

<SignedIn />
<SignedOut />
<UserButton />