Use auth

Access auth state and perform sign-up, sign-in, sign-out, and token management

Overview

useAuth is the primary authentication hook. It returns current token state and functions for all built-in auth operations: sign-up, sign-in, sign-out, password change, and manual token refresh.

Usage Example

React

import { useAuth } from "@sublay/react-js";

function SignInForm() {
  const { initialized, accessToken, signInWithEmailAndPassword, signOut } = useAuth();

  if (!initialized) return <p>Loading...</p>;
  if (accessToken) return <button onClick={signOut}>Sign Out</button>;

  return (
    <button
      onClick={() =>
        signInWithEmailAndPassword({
          email: "[e-mail]",
          password: "password123",
        })
      }
    >
      Sign In
    </button>
  );
}

Returns

useAuth returns an object with the following fields:

initialized · boolean

true once the SDK has attempted to restore a session from the stored refresh token. Always check this before rendering auth-dependent UI.

accessToken · string | null

The current JWT access token, or null if no user is signed in. Expires every 30 minutes; the SDK refreshes it automatically.

refreshToken · string | null

The current JWT refresh token, or null if no user is signed in.

setRefreshToken · function

Manually set a refresh token in Redux state. Useful when integrating external auth flows that hand tokens directly to the SDK.

signUpWithEmailAndPassword · function

Create a new account and sign in. Accepts a SignUpWithEmailAndPasswordProps object. Throws if registration fails.

Parameters:

• email (required) — User’s email address
• password (required) — Password
• name (optional) — Display name
• username (optional) — Unique username
• avatar (optional) — Avatar URL
• bio (optional) — Bio text
• location (optional) — { latitude, longitude }
• birthdate (optional) — Date of birth
• metadata (optional) — Public custom fields
• secureMetadata (optional) — Private custom fields
• avatarFile (optional) — Avatar image file to upload
• avatarOptions (optional) — Image processing options for the avatar
• bannerFile (optional) — Banner image file to upload
• bannerOptions (optional) — Image processing options for the banner

signInWithEmailAndPassword · function

Sign in with an existing account. Accepts { email: string; password: string }. Throws if credentials are invalid.

signOut · function

Sign out the current account. Sends a sign-out request to the server to revoke the refresh token family, then clears local auth state. Throws on error.

changePassword · function

Change the password for the currently authenticated user. Accepts { password: string; newPassword: string }. The current password must be correct. Throws if verification fails.

requestNewAccessToken · function

Manually trigger an access token refresh using the stored refresh token. Returns the new access token string, or undefined if the refresh fails. The SDK handles refresh automatically in most cases; use this only when you need to force a refresh.

Integration Guide

For full integration guidance, see Built-in Auth.