transactional-auth-node

Node.js SDK for Transactional Auth - Token verification and management API client for backend applications.

Installation

npm install transactional-auth-node
# or
yarn add transactional-auth-node
# or
pnpm add transactional-auth-node

Features

• Token Verification - Verify JWT access tokens from Transactional Auth
• Express Middleware - Ready-to-use middleware for Express.js
• Management API Client - Create, update, and manage users programmatically
• Permission & Role Checks - Built-in middleware for authorization

Quick Start

Token Verification

import { verifyToken, decodeToken, isTokenExpired } from 'transactional-auth-node';

// Verify and decode a token
const decoded = await verifyToken(token, 'auth.usetransactional.com', {
  audience: 'https://api.example.com',
});

console.log('User ID:', decoded.sub);
console.log('Scopes:', decoded.scope);

// Decode without verification (for inspection)
const claims = decodeToken(token);

// Check if expired
if (isTokenExpired(token)) {
  console.log('Token is expired');
}

Express Middleware

import express from 'express';
import {
  createAuthMiddleware,
  requirePermissions,
  requireRoles,
  requireScopes,
  optionalAuth,
} from 'transactional-auth-node/express';

const app = express();

// Create the auth middleware
const auth = createAuthMiddleware({
  domain: 'auth.usetransactional.com',
  audience: 'https://api.example.com',
});

// Protect all /api routes
app.use('/api', auth);

// Access the authenticated user
app.get('/api/profile', (req, res) => {
  res.json({
    userId: req.auth?.sub,
    email: req.auth?.email,
  });
});

// Require specific permissions
app.delete('/api/users/:id', requirePermissions('delete:users'), (req, res) => {
  // Only users with 'delete:users' permission can reach here
});

// Require specific roles
app.get('/api/admin', requireRoles('admin'), (req, res) => {
  // Only admins can reach here
});

// Require specific scopes
app.get('/api/data', requireScopes('read:data'), (req, res) => {
  // Only tokens with 'read:data' scope
});

// Optional authentication
app.get('/api/public', optionalAuth({ domain: 'auth.usetransactional.com' }), (req, res) => {
  if (req.auth) {
    res.json({ message: `Hello, ${req.auth.sub}` });
  } else {
    res.json({ message: 'Hello, anonymous' });
  }
});

Management API Client

import { TransactionalAuthClient } from 'transactional-auth-node';

const auth = new TransactionalAuthClient({
  domain: 'auth.usetransactional.com',
  clientId: 'your-management-client-id',
  clientSecret: 'your-management-client-secret',
});

// List users
const { data: users, meta } = await auth.getUsers({
  page: 1,
  limit: 20,
  search: 'john',
});

// Get a specific user
const user = await auth.getUser('user-id');

// Create a user
const newUser = await auth.createUser({
  email: '[email protected]',
  password: 'securepassword',
  name: 'John Doe',
  emailVerified: false,
});

// Update a user
await auth.updateUser('user-id', {
  name: 'Jane Doe',
  userMetadata: { preferences: { theme: 'dark' } },
});

// Block/unblock a user
await auth.blockUser('user-id');
await auth.unblockUser('user-id');

// Send verification email
await auth.sendVerificationEmail('user-id');

// Change password
await auth.changePassword('user-id', 'newpassword');

// Delete a user
await auth.deleteUser('user-id');

// Role management
const roles = await auth.getRoles();
await auth.assignRoleToUser('user-id', 'role-id');
await auth.removeRoleFromUser('user-id', 'role-id');
const userRoles = await auth.getUserRoles('user-id');

API Reference

Token Verification

verifyToken(token, domain, options?)

Verifies a JWT and returns the decoded payload.

| Parameter | Type | Description | |-----------|------|-------------| | token | string | The JWT access token | | domain | string | Auth domain | | options.audience | string | Expected audience | | options.issuer | string | Expected issuer (defaults to domain) |

decodeToken(token)

Decodes a JWT without verification (for inspection only).

isTokenExpired(token)

Returns true if the token is expired.

Express Middleware

createAuthMiddleware(options)

Creates Express middleware for JWT authentication.

| Option | Type | Default | Description | |--------|------|---------|-------------| | domain | string | Required | Auth domain | | audience | string | - | Expected audience | | algorithms | string[] | ['RS256'] | Accepted algorithms | | credentialsRequired | boolean | true | Fail if token missing |

requirePermissions(...permissions)

Middleware to check for required permissions.

requireRoles(...roles)

Middleware to check for required roles (any match).

requireScopes(...scopes)

Middleware to check for required scopes.

optionalAuth(options)

Same as createAuthMiddleware but doesn't fail if token is missing.

Management API Client

Constructor

new TransactionalAuthClient({
  domain: 'auth.usetransactional.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
})

Users

• getUsers(params?) - List users with pagination
• getUser(userId) - Get user by ID
• getUserByEmail(email) - Get user by email
• createUser(data) - Create a new user
• updateUser(userId, data) - Update a user
• deleteUser(userId) - Delete a user
• blockUser(userId) - Block a user
• unblockUser(userId) - Unblock a user
• sendVerificationEmail(userId) - Send verification email
• changePassword(userId, password) - Change password

Applications

• getApplications() - List applications
• getApplication(appId) - Get application by ID

Connections

• getConnections() - List connections
• getConnection(connectionId) - Get connection by ID

Roles

• getRoles() - List roles
• assignRoleToUser(userId, roleId) - Assign role to user
• removeRoleFromUser(userId, roleId) - Remove role from user
• getUserRoles(userId) - Get user's roles

TypeScript

Full TypeScript support with exported types:

import type {
  DecodedToken,
  User,
  CreateUserData,
  UpdateUserData,
  ListUsersParams,
  PaginatedResponse,
  Application,
  Connection,
  Role,
} from 'transactional-auth-node';

License

MIT