@axowl/sdk

The official Axowl SDK for React — drop-in authentication, session management, and permission control.

Install

npm install @axowl/sdk

Quick Start

1. Wrap your app with AxowlProvider

import { AxowlProvider } from '@axowl/sdk';

function App() {
  return (
    <AxowlProvider orgSlug="my-org" appKey="ak_live_xxxxx">
      <YourApp />
    </AxowlProvider>
  );
}

2. Use authentication hooks

import { useAxowl } from '@axowl/sdk';

function LoginPage() {
  const { user, isSignedIn, isLoaded, signIn, signOut } = useAxowl();

  if (!isLoaded) return <p>Loading...</p>;

  if (isSignedIn) {
    return (
      <div>
        <p>Welcome, {user.name}!</p>
        <button onClick={signOut}>Sign Out</button>
      </div>
    );
  }

  return (
    <div>
      <button onClick={() => signIn.magicLink('[email protected]')}>
        Send Magic Link
      </button>
      <button onClick={() => signIn.social({ provider: 'google', idToken: '...' })}>
        Sign in with Google
      </button>
    </div>
  );
}

3. Check permissions

import { usePermission } from '@axowl/sdk';

function Dashboard() {
  const { can, canAll, canAny } = usePermission();

  if (!can('dashboard.view')) {
    return <p>Access denied</p>;
  }

  return (
    <div>
      <h1>Dashboard</h1>
      {can('report.export') && <button>Export Report</button>}
      {canAny(['settings.view', 'settings.edit']) && <a href="/settings">Settings</a>}
    </div>
  );
}

4. Access organization info

import { useOrg } from '@axowl/sdk';

function OrgInfo() {
  const { currentOrganization, organizations, membershipType } = useOrg();

  return (
    <div>
      <p>Current: {currentOrganization?.orgName}</p>
      <p>Role: {membershipType}</p>
      <p>Total orgs: {organizations.length}</p>
    </div>
  );
}

Hooks

| Hook | Returns | Description | |---|---|---| | useAxowl() | { user, isSignedIn, isLoaded, signIn, signOut, refreshUser } | Core auth state and actions | | usePermission() | { can, canAll, canAny, checkRemote, permissions } | Permission checking | | useSession() | { isSignedIn, expiresAt, refresh, revokeAll } | Session management | | useOrg() | { currentOrganization, organizations, orgSlug, connectedId, membershipType } | Organization context |

Components

import { SignInButton, UserButton } from '@axowl/sdk';

// Shows "Sign In" button when not authenticated (hidden when signed in)
<SignInButton className="btn" />

// Shows user name/email when authenticated (hidden when signed out)
<UserButton />

Sign-in Methods

const { signIn } = useAxowl();

// Magic link (email)
await signIn.magicLink('[email protected]');

// Social (Google, Line)
await signIn.social({ provider: 'google', idToken: '...' });

// Federated (OIDC — Keycloak, Clerk, etc.)
await signIn.federated({ orgSlug: 'my-org', provider: 'keycloak', idToken: '...' });

// Passkey (FIDO2)
await signIn.passkey('[email protected]', credentialResponseJson);

Remote Permission Check

For high-security operations, verify permissions server-side:

const { checkRemote } = usePermission();

async function handleSensitiveAction() {
  const allowed = await checkRemote('billing.charge');
  if (allowed) {
    // proceed
  }
}

Configuration

<AxowlProvider
  orgSlug="my-org"               // Required: organization slug
  appKey="ak_live_xxxxx"         // Required: application key
  baseUrl="https://auth.axowl.com"  // Optional: API URL
  tokenStorage="localStorage"    // Optional: localStorage | sessionStorage | memory
  autoRefresh={true}             // Optional: auto-refresh tokens (default: true)
  refreshThresholdSeconds={60}   // Optional: refresh before expiry in seconds
>

Requirements

• React 18+ or React 19+
• TypeScript 5+ (recommended)

License

MIT