Integrating Hawcx Backend SDK into Existing Node.js Projects

This guide walks through adding Hawcx OAuth authentication to an existing Node.js backend.

Step 1: Install the SDK

npm install @hawcx/oauth-client

Step 2: Set Up Environment Variables

Create a .env file or configure your environment with:

# Config ID — from Admin Console → Project Settings
HAWCX_CONFIG_ID="<Config ID from Admin Console>"
# Base URL — from Admin Console → Project Settings (environment-specific)
HAWCX_BASE_URL="<Base URL from Admin Console>"

# Optional (for delegation / MFA management)
HAWCX_SECRET_KEY=hwx_sk_v1_...

Where to find these values: Open the Hawcx Admin Console, go to Project Settings, and copy both the Config ID and Base URL. The base URL is unique to your environment — there is no universal default.

Load environment variables in your application:

import dotenv from 'dotenv';
dotenv.config();

Step 3: Create an Exchange Endpoint

Create a new route to handle Hawcx code exchange:

import express from 'express';
import { HawcxOAuth } from '@hawcx/oauth-client';

const router = express.Router();

const oauth = new HawcxOAuth({
  configId: process.env.HAWCX_CONFIG_ID!,
  baseUrl: process.env.HAWCX_BASE_URL
});

router.post('/exchange', async (req, res) => {
  try {
    const { authCode, codeVerifier } = req.body;

    if (!authCode || !codeVerifier) {
      return res.status(400).json({ error: 'Missing authCode or codeVerifier' });
    }

    const { claims } = await oauth.exchangeCode(authCode, codeVerifier);

    // Find or create user in your database
    const user = await findOrCreateUser({
      id: claims.sub,
      email: claims.email
    });

    // Create your application's session/JWT
    const sessionToken = generateSessionToken(user);

    res.json({
      success: true,
      sessionToken,
      user: {
        id: user.id,
        email: user.email
      }
    });
  } catch (error) {
    console.error('Hawcx exchange error:', error);
    res.status(401).json({ error: 'Authentication failed' });
  }
});

export default router;

Step 4: Integrate with Your User Management

Update your user service to handle Hawcx identities:

// services/userService.ts
import db from '../db';

interface HawcxUser {
  id: string;  // Hawcx user ID (sub claim)
  email?: string;
}

export async function findOrCreateUser(hawcxUser: HawcxUser) {
  let user = await db.users.findOne({ hawcx_id: hawcxUser.id });

  if (!user) {
    user = await db.users.create({
      hawcx_id: hawcxUser.id,
      email: hawcxUser.email
    });
  }

  return user;
}

Optional: Backend-Driven MFA Management

If you need to manage MFA from your backend, use the delegation client with your secret key blob:

import { DelegationClient, MfaMethod } from '@hawcx/oauth-client';

const client = DelegationClient.fromSecretKey({
  secretKey: process.env.HAWCX_SECRET_KEY!,
  baseUrl: process.env.HAWCX_BASE_URL!,
  apiKey: process.env.HAWCX_CONFIG_ID
});

const result = await client.mfa.initiate({
  userId: '[email protected]',
  mfaMethod: MfaMethod.SMS,
  phoneNumber: '+15551234567'
});

await client.mfa.verify({
  userId: '[email protected]',
  sessionId: result.session_id,
  otp: '123456'
});

Integrate in Existing Node.js Project