Node.js SDK API Reference

HawcxOAuth

Initialize the OAuth client and exchange codes for verified claims.

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

const oauth = new HawcxOAuth({
  configId: process.env.HAWCX_API_KEY!,
  baseUrl: process.env.HAWCX_BASE_URL,  // optional
  jwksCacheTtl: 60 * 60 * 1000,         // optional
  timeout: 10_000                       // optional
});

Config:

Property	Type	Required	Description
`configId`	`string`	Yes	Hawcx Config ID (public identifier)
`baseUrl`	`string`	No	Hawcx base URL (default: `https://api.hawcx.com`)
`jwksCacheTtl`	`number`	No	JWKS cache TTL in ms (default: 1 hour)
`timeout`	`number`	No	Request timeout in ms (default: 10000)

`exchangeCode(code, codeVerifier)`

Exchange an authorization code for verified claims.

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

// claims.sub = user ID
// claims.email = verified email (if present)

Returns:

Property	Type	Description
`idToken`	`string`	Raw JWT (do not use as access token)
`claims`	`object`	Verified JWT claims

`verifyToken(token)`

Verify a JWT and return its claims.

const claims = await oauth.verifyToken(idToken);

`clearCache()`

Clear the JWKS cache (useful for key rotation or tests).

oauth.clearCache();

Error Types

import { TokenExchangeError, TokenVerificationError } from '@hawcx/oauth-client';

TokenExchangeError — code exchange failed (invalid/expired code, network error)
TokenVerificationError — JWT verification failed (bad signature, malformed token)

Delegation Client

Use the delegation client for backend-driven MFA setup and user/device management.

`DelegationClient.fromSecretKey(options)`

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

const client = DelegationClient.fromSecretKey({
  secretKey: process.env.HAWCX_SECRET_KEY!,
  baseUrl: 'https://api.hawcx.com',
  apiKey: process.env.HAWCX_API_KEY
});

`DelegationClient.fromKeys(options)`

const client = DelegationClient.fromKeys({
  spSigningKey: process.env.SP_ED25519_PRIVATE_KEY_PEM!,
  spEncryptionKey: process.env.SP_X25519_PRIVATE_KEY_PEM!,
  idpVerifyKey: process.env.IDP_ED25519_PUBLIC_KEY_PEM!,
  idpEncryptionKey: process.env.IDP_X25519_PUBLIC_KEY_PEM!,
  spKid: process.env.SP_KEY_ID!,
  idpKid: process.env.IDP_KEY_ID!,
  baseUrl: 'https://api.hawcx.com',
  apiKey: process.env.HAWCX_API_KEY
});

MFA

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

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

Users

const creds = await client.users.getCredentials('[email protected]');

Devices

const devices = await client.devices.list('[email protected]');
await client.devices.revoke({ userId: '[email protected]', deviceId: 'h2index' });

Node.js SDK API Reference

On this page