The Authsignal React SDK builds on top of the Web SDK by providing UI components which can be added to your React app.

The Authsignal React SDK currently only supports re-authentication flows.

An example of the UI components in a checkout flow.

GitHub repository

​
Installation

npm install @authsignal/react

​
AuthsignalProvider component

The AuthsignalProvider component allows you to use the useAuthsignal hook. Render the AuthsignalProvider component at the root of your application so that it is available everywhere you need it.

import { AuthsignalProvider } from "@authsignal/react";

import { Checkout } from "./Checkout";

export function App() {
  return (
    <AuthsignalProvider tenantId="{{TENANT_ID}}" baseUrl="{{BASE_URL}}">
      <Checkout />
    </AuthsignalProvider>
  );
}

The AuthsignalProvider component accepts the following props:

​
tenantId
string
required

Your tenant ID. It can be found in the API keys section.

​
baseUrl
string

Your tenant’s API URL. It can be found in the API keys section.

​
appearance
object

Customize the design of the UI components.

​
useAuthsignal hook

The useAuthsignal hook returns two functions, startChallenge and startChallengeAsync, that you can use to trigger the authentication flow.

Both functions require a token to be passed as an argument. The token should be returned by your server after tracking an action.

​
startChallenge

The startChallenge function triggers the authentication flow.

import { useAuthsignal } from "@authsignal/react";

export function Checkout() {
  const { startChallenge } = useAuthsignal();

  const handlePayment = async () => {
    const response = await fetch("/api/payment", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
    });

    const data = await response.json();

    if (data.token) {
      startChallenge({
        token: data.token,
        onChallengeSuccess: ({ token }) => {
          // Challenge was successful
          // Send the token to your server to validate the challenge
        },
        onCancel: () => {
          // User cancelled the challenge
        },
        onTokenExpired: () => {
          // Token expired
        },
      });
    }
  };

  return (
    <div>
      <button type="button" onClick={handlePayment}>
        Pay
      </button>
    </div>
  );
}

As well as a token, the startChallenge function accepts the following callbacks:

​
onChallengeSuccess
function

A callback function that is called when the challenge is successful. It receives an object with a token property. This token should be sent to your server to validate the challenge.

​
onCancel
function

A callback function that is called when the user cancels the challenge.

​
onTokenExpired
function

A callback function that is called when the token expires.

​
startChallengeAsync

Alternatively, you can use the startChallengeAsync function, which returns a Promise that resolves with a token when the challenge is successful. It will throw a ChallengeError if the user cancels the challenge or the token expires.

import { useAuthsignal, ChallengeError } from "@authsignal/react";

export function Checkout() {
  const { startChallengeAsync } = useAuthsignal();

  const handlePayment = async () => {
    const response = await fetch("/api/payment", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
    });

    const data = await response.json();

    if (data.token) {
      try {
        const { token } = await startChallengeAsync({
          token: data.token,
        });

        // Challenge was successful
        // Send the token to your server to validate the challenge
      } catch (e) {
        if (e instanceof ChallengeError) {
          if (e.code === "USER_CANCELED") {
            // User cancelled the challenge
          } else if (e.code === "TOKEN_EXPIRED") {
            // Token expired
          }
        }
      }
    }
  };

  return (
    <div>
      <button type="button" onClick={handlePayment}>
        Pay
      </button>
    </div>
  );
}

​
Customizing the appearance

You can customize the appearance of the UI components by passing an appearance prop to the AuthsignalProvider component.

import { AuthsignalProvider } from "@authsignal/react";

import { Checkout } from "./Checkout";

export function App() {
  return (
    <AuthsignalProvider
      tenantId="{{TENANT_ID}}"
      baseUrl="{{BASE_URL}}"
      appearance={{
        variables: {
          borderRadius: "0.5rem",
          colorBackground: "#0A2540",
          colorPrimary: "#EFC078",
          colorPrimaryForeground: "#1A1B25",
          colorForeground: "white",
        },
      }}
    >
      <Checkout />
    </AuthsignalProvider>
  );
}