react-tenxyte

react-tenxyte

The official, fully-typed React and Next.js (Server/Client) SDK for the Tenxyte Authentication and RBAC platform.

It provides seamless integration for managing user sessions, Multi-Factor Authentication (TOTP, WebAuthn/Passkeys), Multi-tenant Organizations, and Role-Based Access Control (RBAC) securely out of the box.

Table of Contents

• Features
• Installation
• Getting Started (React Frontend)
• Role-Based Access Control (RBAC)
• Next.js App Router Support (SSR)
• Core API Usage (Vanilla TypeScript)
  • Authentication API
  • Security API (2FA & WebAuthn)
  • User & Organization API
• License

Features

• ⚛️ First-Class React Support: Context Providers, Custom Hooks (useTenxyteAuth), and HOCs (withAuth).
• 🛡️ Built-in RBAC: Protect UI elements natively using the <Can /> component.
• 🚀 Next.js App Router Ready: First-class support for SSR cookies() and Server Components.
• 🔑 Advanced Security: Full support for TOTP (Authenticator Apps) and Passwordless WebAuthn (Passkeys / Biometrics).
• 🏢 Multi-Tenant Ready: Native organization switching (switchOrganization).
• 🤖 Zero-Config Token Refresh: Built-in interceptors to automatically queue requests and refresh access tokens silently in the background.

Installation

npm install react-tenxyte
# or
yarn add react-tenxyte
# or
pnpm add react-tenxyte

Getting Started (React Frontend)

Wrap your entire React application with the TenxyteProvider. This will automatically fetch the user session on mount and provide authentication state to all children.

1. Initialize the Provider

import React from 'react';
import { TenxyteProvider, TenxyteClient } from 'react-tenxyte';
import App from './App';

// Initialize the Tenxyte Vanilla Client
const client = new TenxyteClient({
  apiUrl: 'https://api.your-backend.com', // Your Django Tenxyte backend URL
  accessKey: 'your_access_key',           // Your public App Access Key
  accessSecret: 'your_access_secret'      // Your public App Secret
});

const Root = () => (
  <TenxyteProvider client={client}>
    <App />
  </TenxyteProvider>
);

export default Root;

2. Access the Custom Hook

Use useTenxyteAuth in any component to access the user session, current organization, loading state, and helper methods.

import { useTenxyteAuth } from 'react-tenxyte';

export const UserProfile = () => {
  const { user, isAuthenticated, isLoading, logout, currentOrg, switchOrganization } = useTenxyteAuth();

  if (isLoading) return <div>Loading...</div>;

  if (!isAuthenticated) return <div>Please log in!</div>;

  return (
    <div>
      <h1>Welcome back, {user?.email}</h1>
      <p>Current Organization: {currentOrg?.name || 'Personal Account'}</p>
      
      <button onClick={() => switchOrganization('my-company-slug')}>
        Switch to My Company Workspace
      </button>

      {/* logout(true) logs out from all devices */}
      <button onClick={() => logout(false)}>Logout</button>
    </div>
  );
};

3. Protect Pages via Higher Order Component

Use the withAuth HOC to prevent non-authenticated users from viewing a specialized component.

import { withAuth } from 'react-tenxyte';

const Dashboard = () => {
  return <div>Strictly Confidential Dashboard</div>;
};

// If not authenticated, the user sees the fallback.
export default withAuth(Dashboard, <div>You are not allowed to view this page.</div>);

Role-Based Access Control (RBAC)

Tenxyte provides a declarative <Can /> component to effortlessly show or hide UI elements based on the Roles or Permissions of the logged-in user. (Requires TenxyteProvider).

Show elements by Role

import { Can } from 'react-tenxyte';

const AdminPanelButton = () => {
    return (
        <Can role={['Admin', 'SuperAdmin']} fallback={<span>Access Denied</span>}>
            <button>Delete Entire Project</button>
        </Can>
    );
};

Show elements by Permission

import { Can } from 'react-tenxyte';

const EditPostForm = () => {
    return (
        // Renders null if the user lacks the permission natively
        <Can permission="edit:posts">
            <form>
               <textarea placeholder="Write awesome content..."></textarea>
               <button type="submit">Save</button>
            </form>
        </Can>
    );
};

Next.js App Router Support (SSR)

If you are using Next.js Server Components, you can natively extract session securely using HTTP-Only cookies without hydrating exactly as you would on the client.

Server Component Usage (page.tsx or layout.tsx)

import { createNextServerClient, getUserSession } from 'react-tenxyte/next';
import { redirect } from 'next/navigation';

export default async function ProtectedServerDashboard() {
  // Use strictly the server initialization method, it binds to `next/headers` cookies()
  const serverClient = createNextServerClient(
      process.env.NEXT_PUBLIC_API_URL!, 
      process.env.NEXT_PUBLIC_TENXYTE_ACCESS_KEY!, 
      process.env.NEXT_PUBLIC_TENXYTE_ACCESS_SECRET!
  );

  // Directly returns the User object by verifying cookies from the incoming request.
  const user = await getUserSession(serverClient);

  if (!user) {
    redirect('/login');
  }

  return <div>Hello securely from the Server, {user.email}!</div>;
}

Core API Usage (Vanilla TypeScript)

If you do not use React, or want to perform custom backend logic (e.g. your own Login Forms), the Core TenxyteClient grants direct access to all SDK APIs.

Authentication API

Execute Logins and Passwords interactions directly. The tokens are stored automatically in LocalStorage (in the browser), and access tokens are refreshed silently under the hood.

import { TenxyteClient } from 'react-tenxyte';

const client = new TenxyteClient({
  apiUrl: 'https://api.your-backend.com',
  accessKey: 'your_access_key',
  accessSecret: 'your_access_secret'
});

// Login via email/password
async function handleLogin(email, password) {
  try {
    const res = await client.auth.login(email, password);
    console.log('Login successful!', res.message);
    
    // Check if 2FA is required before receiving the tokens
    if (res.requires_2fa || res.requires_webauthn) {
      console.log("Proceed to second factor confirmation step.");
    }
  } catch (err) {
    console.error('Invalid credentials');
  }
}

Security API (2FA & WebAuthn)

Easily handle complex workflows like native Biometrics (Passkeys) and Authenticator Apps.

Passkeys (WebAuthn)

// 1. Ask the server for an authentication challenge
const startPayload = await client.security.authenticateWebAuthnStart('[e-mail]');

// 2. You will pass `startPayload.challenge` to the native navigator.credentials.get() API
// Example (Simplified): const authResponse = await navigator.credentials.get({ publicKey: ... })

// 3. Complete authentication
const finalTokens = await client.security.authenticateWebAuthnFinish({ 
    response: authResponse // Output of the navigator API
});

Authenticator Apps (TOTP)

// Setup a new App (Server returns QR Code URI and secret)
const totpSetup = await client.security.setupTOTP();
console.log('Scan this with Google Authenticator:', totpSetup.uri);

// Confirm code to enable
const confirmed = await client.security.confirmTOTP('123456');
console.log('Backup Codes:', confirmed.backup_codes);

// Disable TOTP
await client.security.disableTOTP('123456');

User & Organization API

Retrieve metadata or manipulate organizations.

// Get the currently authenticated profile
const me = await client.user.getProfile();
console.log('My Roles:', me.roles);

// Create a new tenant/organization
const newOrg = await client.organization.create('Acme Corp', 'acme-corp');

// Update user settings globally
await client.user.updateProfile({ 
    first_name: 'John', 
    last_name: 'Doe' 
});

License

MIT