Skip to content
Bkper
app.header.homeapp.header.docs

@bkper/web-auth

npm GitHub

@bkper/web-auth

OAuth authentication SDK for apps on the Bkper Platform (*.bkper.app subdomains).

Installation

Terminal window
bun add @bkper/web-auth

Quick Start

import { BkperAuth } from '@bkper/web-auth';


// Initialize client with callbacks
const auth = new BkperAuth({
    onLoginSuccess: () => {
        console.log('User authenticated!');
        loadUserData();
    },
    onLoginRequired: () => {
        console.log('Please sign in');
        showLoginButton();
    },
});


// Initialize authentication flow on app load
await auth.init();


// Get access token for API calls
const token = auth.getAccessToken();
if (token) {
    fetch('/api/data', {
        headers: { Authorization: `Bearer ${token}` },
    });
}

Handling Token Expiration

Access tokens expire and need to be refreshed. The recommended pattern is to handle authentication errors and retry:

async function apiRequest(url: string, options: RequestInit = {}) {
    // Add auth header
    const token = auth.getAccessToken();
    options.headers = {
        ...options.headers,
        Authorization: `Bearer ${token}`,
    };


    const response = await fetch(url, options);


    // Handle expired token
    if (response.status === 403) {
        try {
            await auth.refresh();
            options.headers = {
                ...options.headers,
                Authorization: `Bearer ${auth.getAccessToken()}`,
            };
            return fetch(url, options); // Retry once
        } catch (error) {
            // Refresh failed - the onError callback will be triggered
            // Handle the error appropriately (e.g., redirect to login, show error message)
            throw error;
        }
    }


    return response;
}

What’s Included

  • OAuth authentication SDK for apps on *.bkper.app subdomains
  • Callback-based API for authentication events
  • OAuth flow with in-memory token management
  • Token refresh mechanism
  • TypeScript support with full type definitions

How It Works

Session Persistence:

  • Access tokens are stored in-memory (cleared on page refresh)
  • Sessions persist via HTTP-only cookies scoped to the .bkper.app domain
  • Call init() on app load to restore the session from cookies

Note: This SDK only works for apps hosted on *.bkper.app subdomains. For apps on other domains, use a valid access token directly with bkper-js.

Security:

  • HTTP-only cookies protect refresh tokens from XSS
  • In-memory access tokens minimize exposure

TypeScript Support

This package is written in TypeScript and provides full type definitions out of the box. All public APIs are fully typed, including callbacks and configuration options.

import { BkperAuth, BkperAuthConfig } from '@bkper/web-auth';


const config: BkperAuthConfig = {
    onLoginSuccess: () => console.log('Authenticated'),
    onError: error => console.error('Auth error:', error),
};


const auth = new BkperAuth(config);

Browser Compatibility

This package requires a modern browser with support for:

The app must be deployed to a *.bkper.app subdomain for session cookies to work.