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 (public identifier)
HAWCX_API_KEY=your_config_id
# Optional base URL override
HAWCX_BASE_URL=https://api.hawcx.com

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

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_API_KEY!,
  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 || 'https://api.hawcx.com',
  apiKey: process.env.HAWCX_API_KEY
});

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