Quickstart

The fastest path for a web app is the @axowl/sdk React package (or hosted login). Your users authenticate (passkey / magic link / social / SSO) and you get a verified session — you never handle credentials.

React (@axowl/sdk)

npm install @axowl/sdk

import { AxowlProvider, useAxowl, usePermission } from '@axowl/sdk';

// 1. Wrap your app with your org slug + your client's Client ID
<AxowlProvider orgSlug="my-org" clientId="client_..." baseUrl="https://api.axowl.com">
  <App />
</AxowlProvider>

// 2. Use hooks
function Page() {
  const { user, isSignedIn, signIn, signOut } = useAxowl();
  const { can } = usePermission();
  if (!isSignedIn) return <button onClick={() => signIn.magicLink('[email protected]')}>Sign in</button>;
  if (!can('dashboard.view')) return <p>Access denied</p>;
  return <p>Welcome, {user.name}!</p>;
}

clientId is the Client ID (client_…) of the client you registered — one per platform and environment; find it under Applications → your client → App Keys. baseUrl is the Axowl API host; set it to https://api.axowl.com, the host your backend verifies tokens against. Prefer the drop-in <SignIn /> component when you want the app group’s configured methods (passkey, magic link, social) rendered for you.

Express backend (@axowl/sdk-backend)

import { axowlMiddleware, requirePermission } from '@axowl/sdk-backend';

app.use(axowlMiddleware({ orgSlug: 'my-org', apiKey: 'ah_live_xxxxx', audience: 'client_...' }));
app.get('/api/reports', requirePermission('report.view'), (req, res) =>
  res.json({ userId: req.axowl.userId }));

The middleware reads the Authorization: Bearer token, verifies its RS256 signature against your org’s JWKS and sets req.axowl (userId, email, orgSlug, permissions); a missing or invalid token answers 401, and requirePermission answers 403 when a scope is missing. apiKey is an org API key (ah_live_...) — see Public API. audience is your client’s Client ID: only tokens issued to that client are accepted. It is required from @axowl/sdk-backend 0.4.0 (a config without it throws when the app starts); earlier versions skip the check when it is not set, so always set it. For Next.js route handlers use getAuthAsync / canAccess from @axowl/sdk-backend/next.

Or use hosted login

Send users to the Axowl-hosted portal (https://login.axowl.com/login/{clientId}?redirect_url=…) and receive a one-time code at your callback, then exchange it for the user’s JWT with POST /api/public/apps/{clientId}/auth/session/exchange (the JWT is verified against the org JWKS — no shared secret). See Hosted login and OIDC / OAuth2.

Next steps

• Identity SDK — permission enforcement.
• Authentication model — org-native vs. end-user.