Authentication Overview

The SDK handles JWT access tokens, refresh tokens, and session persistence automatically. Frontend developers never need to manually attach Authorization headers.

Listening to Auth State

The SDK uses an event emitter pattern. You can subscribe to onAuthStateChanged to reactively update your UI when a user logs in or out. This is highly useful for React useEffect or Vue onMounted.

// Subscribe to auth changes
const unsubscribe = sdk.auth.onAuthStateChanged((user) => {
  if (user) {
    console.log(`Welcome back, ${user.username}! 2FA: ${user.isTwoFactorEnabled}`);
  } else {
    console.log('User is logged out.');
    // Show login screen
  }
});

// Call this when your component unmounts to prevent memory leaks
// unsubscribe();

Session Persistence (Auto-Restore)

If a user refreshes the page, the browser loses memory of the access token.

The SDK automatically detects a stored refresh token on initialization and silently calls the backend /v1/auth/refresh endpoint. Once finished, it fires onAuthStateChanged with the restored user. No UI flickering or forced logouts required.

Getting the Current User

You can synchronously access the current user object anywhere in your app:

const user = sdk.auth.getCurrentUser();

if (sdk.auth.isAuthenticated()) {
  console.log(`User ID: ${user.id}`);
}

To force a fresh fetch of the user's profile from the backend:

const freshUser = await sdk.auth.getProfile();

Logout

await sdk.auth.logout();

This invalidates the token on the backend and immediately clears all local SDK state, firing onAuthStateChanged with null.