@authvora/node

Official Node.js/TypeScript SDK for Authvora — authentication, token management, and Express middleware for modern applications.

Install

npm install @authvora/node

Quick Start

import { Authvora } from "@authvora/node";

// Cloud — just your tenant ID
const authvora = new Authvora({
  tenantId: "your-tenant-id",
});

// Self-hosted — override the base URL
const authvora = new Authvora({
  tenantId: "your-tenant-id",
  baseUrl: "https://auth.mycompany.com",
});

Register a User

const { user, access_token } = await authvora.auth.register({
  email: "[email protected]",
  password: "securepassword123",
  name: "Alice Smith",
});

console.log(user.id); // "d347bd20-5d41-..."

Login

const result = await authvora.auth.login({
  email: "[email protected]",
  password: "securepassword123",
});

if ("mfa_required" in result) {
  // MFA is required — prompt the user for a code
  const session = await authvora.auth.verifyMFA(result.mfa_token, "123456");
} else {
  console.log(result.access_token);
}

Google OAuth

const session = await authvora.auth.loginWithGoogle({
  code: "google-authorization-code",
  redirect_uri: "https://yourapp.com/callback",
});

Token Refresh

Tokens are refreshed automatically when making authenticated requests. You can also refresh manually:

const tokens = await authvora.auth.refreshToken("your-refresh-token");
// tokens.access_token
// tokens.refresh_token
// tokens.expires_in

Logout

await authvora.auth.logout("your-refresh-token");

Get Current User

const user = await authvora.auth.getUser();
console.log(user.email);

Get User by ID

const user = await authvora.auth.getUserById("user-uuid");

Get JWKS (Public Keys)

const jwks = await authvora.auth.getJWKS();

Express Middleware

Protect routes by verifying JWT tokens automatically:

import express from "express";
import { Authvora } from "@authvora/node";

const app = express();
const authvora = new Authvora({ tenantId: "your-tenant-id" });

// Protect all routes under /api
app.use("/api", authvora.middleware());

app.get("/api/profile", (req, res) => {
  // req.authvora is populated by the middleware
  const { user, tenantId } = req.authvora;
  res.json({ id: user.id, email: user.email, tenantId });
});

The middleware:

• Extracts the Bearer token from the Authorization header
• Decodes and validates JWT claims (sub, tid, exp)
• Rejects expired or malformed tokens with a 401 response
• Attaches req.authvora with user, token, and tenantId

Configuration

const authvora = new Authvora({
  tenantId: "your-tenant-id",
  baseUrl: "https://auth.mycompany.com", // optional, defaults to https://api.authvora.com
  apiKey: "your-api-key",                // optional, for server-side calls
});

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | tenantId | string | Yes | — | Your tenant UUID | | baseUrl | string | No | https://api.authvora.com | Authvora API URL (override for self-hosted) | | apiKey | string | No | — | API key sent as X-API-Key header |

Error Handling

All methods throw an AuthvoraError on failure:

import type { AuthvoraError } from "@authvora/node";

try {
  await authvora.auth.login({ email: "[email protected]", password: "wrong" });
} catch (err) {
  const error = err as AuthvoraError;
  console.log(error.code);    // "INVALID_CREDENTIALS"
  console.log(error.message); // "Invalid email or password"
  console.log(error.status);  // 401
}

| Error Code | Status | Meaning | |-----------|--------|---------| | INVALID_CREDENTIALS | 401 | Wrong email or password | | TOKEN_EXPIRED | 401 | Access token expired | | TOKEN_INVALID | 401 | Malformed or tampered token | | TOKEN_REQUIRED | 401 | Missing authentication | | EMAIL_EXISTS | 409 | Email already registered | | RATE_LIMITED | 429 | Too many requests | | NETWORK_ERROR | 0 | Could not reach the server |

TypeScript Types

All types are exported:

import type {
  AuthvoraConfig,
  User,
  AuthResponse,
  MFARequiredResponse,
  TokenPair,
  RegisterParams,
  LoginParams,
  OAuthGoogleParams,
  AuthvoraError,
  AuthvoraRequest,
} from "@authvora/node";

Requirements

• Node.js 18+ (uses native fetch)
• TypeScript 5.0+ (for type declarations)

License

MIT