@authn-sh/sdk-node

Node.js / Edge-runtime backend SDK for authn.sh.

Mirrors @authn-sh/sdk-php — BAPI resource managers, session-JWT verification, webhook signature verification. The frontend counterpart is @authn-sh/sdk-js.

Runs anywhere fetch exists: Node 18+, Cloudflare Workers, Vercel Edge, Bun, Deno.

Install

npm install @authn-sh/sdk-node

BAPI client

import { Authn } from '@authn-sh/sdk-node';

const authn = new Authn({ secretKey: process.env.AUTHN_SECRET_KEY! });

// Users
const user = await authn.users.get('user_01HXYZ');
await authn.users.ban('user_01HXYZ');
const fresh = await authn.users.create({ first_name: 'Alice', email_addresses: ['[email protected]'] });

// Sessions
const session = await authn.sessions.get('sess_01HXYZ');
const jwt = await authn.sessions.getToken('sess_01HXYZ', 'my-jwt-template');

// Organizations + nested managers
const org = await authn.organizations.create({ name: 'Acme', slug: 'acme' });
await authn.organizations.members(org.id).create({ userId: user.id, role: 'org:admin' });
await authn.organizations.invitations(org.id).create({ email_address: '[email protected]', role: 'org:member' });
await authn.organizations.domains(org.id).create('acme.com', 'automatic_invitation');

// Social providers + phone numbers + external accounts + SMS templates
await authn.oauthProviders.list();
await authn.phoneNumbers.list({ userId: user.id } as any);
await authn.externalAccounts.list({ userId: user.id } as any);
await authn.smsTemplates.get('verification_code');

// Instance settings
const instance = await authn.instance.get();
await authn.instance.update({ multi_factor: { phone_code: { enabled: true } } });

Errors from the API surface as AuthnHttpError (status, code, requestId, errors[]).

Session-JWT verification

import { TokenVerifier } from '@authn-sh/sdk-node';

const verifier = new TokenVerifier({ publishableKey: process.env.AUTHN_PUBLISHABLE_KEY! });

// In your auth middleware:
const cookie = req.cookies['__session'];
const claims = await verifier.verify(cookie);  // throws AuthnTokenInvalidError on bad token

console.log(claims.sub);                        // user_…
console.log(claims.organization?.role);         // 'org:admin'
console.log(claims.hasPermission('org:billing:read'));
console.log(claims.hasVerifiedPhoneNumber());
console.log(claims.preferredSecondFactor());    // 'totp' | 'phone_code' | 'backup_code' | null

For "best-effort" auth that falls back to unauthenticated, use tryVerify() — returns null instead of throwing.

The verifier resolves the FAPI host from the publishableKey; pass frontendApiUrl explicitly when self-hosting on a custom domain. JWKS is fetched once and cached in memory (default 10 min TTL).

Webhook signature verification

import express from 'express';
import { WebhookSignatureVerifier } from '@authn-sh/sdk-node';

const app = express();
const verifier = new WebhookSignatureVerifier({
  signingSecret: process.env.AUTHN_WEBHOOK_SECRET!,
});

app.post('/webhooks/authn', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = verifier.verify(req.body.toString('utf8'), req.headers);
    switch (event.type) {
      case 'user.created':       /* … */; break;
      case 'phoneNumber.verified': /* … */; break;
    }
    res.status(204).end();
  } catch {
    res.status(400).end();
  }
});

To rotate the signing secret without downtime, pass an array — the verifier accepts a request if any provided signature matches any secret:

new WebhookSignatureVerifier({ signingSecret: [oldSecret, newSecret] });

Runtime support

| Runtime | Status | | ----------------- | -------------------------------------------- | | Node.js 18+ | ✓ first-class | | Cloudflare Workers | ✓ (uses globalThis.fetch + node:crypto) | | Vercel Edge | ✓ | | Bun | ✓ | | Deno | ✓ via npm: specifier |

The webhook verifier imports node:crypto. On edge runtimes that polyfill it (Workers, Vercel Edge), no action is needed.

License

AGPL-3.0-only — see LICENSE. For commercially licensed deployments, contact authn.sh.