transactional-auth-node

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

Installation

``bash
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

$3

`ts
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');
}
`

$3

`ts
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' });
}
});
`

$3

`ts
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: 'user@example.com',
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

$3

#### 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.

$3

#### 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.

$3

#### Constructor

`ts
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:

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

License

MIT