API reference

createAuthUrl(options)

Generates an HMAC-signed redirect URL and a cryptographic nonce. Async — it signs via the Web Crypto API, so it returns a Promise and must be awaited. It performs no network call.

Returns Promise<{ url: string, nonce: string, sig: string }> — store nonce in the user session and hand url to the browser.

URL signing

The signature covers the canonical query string: every param except sig, sorted by raw key, then each key and value percent-encoded exactly like JavaScript's encodeURIComponent (state=a&b → state=a%26b), joined as key=value pairs with &. Other languages: !'()* stay unescaped, which Python's quote and PHP's rawurlencode escape by default. That string is HMAC-SHA256'd with secret and appended as sig (64 lowercase hex chars):

/voice-auth?space_id=…&nonce=…&state=…&env=…&sdk_origin=…&sig=<hmac-sha256-hex>

Because every other param is covered, changing any of them after signing invalidates sig. Build the URL once, on the server, and pass it through untouched.

verifyAuthUrlSignature(url, secret)

Verifies the sig on an auth URL produced by createAuthUrl. Async. Rebuilds the canonical string from the URL's remaining params and compares in constant time via crypto.subtle.verify. Rejects a URL that repeats a query param. Server-side only — it needs the secret.

import { verifyAuthUrlSignature, InvalidAuthUrlSignatureError } from "@helix-id/node";

try {
  await verifyAuthUrlSignature(url, process.env.HELIX_SECRET);
} catch (error) {
  if (error instanceof InvalidAuthUrlSignatureError) {
    // URL is unsigned or was tampered with — do not redirect the user
  }
}

Returns Promise<void> — resolves when the signature is valid.

Throws InvalidAuthUrlSignatureError when sig is missing or does not match, or a query param repeats.

Most integrations never call this: your own server produced the URL, so there is nothing to check. It is there for architectures where the URL crosses a trust boundary between services — a gateway, a BFF, or a queue — and the receiving side wants proof it was not rewritten in transit.

verifyCallback(query, options)

Verifies the HMAC-signed callback payload and returns the parsed result. Async — it uses the Web Crypto API, so it returns a Promise and must be awaited. The first argument is the raw callback query, every field a plain string.

Returns Promise<{ status, statusCode, logId, state, enrollmentId?, referenceList? }> — enrollmentId is present when the space has Voice MFA or Reference List enabled, absent otherwise. referenceList is { result, matchedEnrollmentId?, matchedCategory? } on a new enrollment in a Reference List space — see Reference List results.

Throws InvalidSignatureError, NonceMismatchError, ExpiredTimestampError, MalformedCallbackError.

Reference List management

People enter your Reference List only when your server adds them. After verifying a voice-auth callback, store its enrollmentId against your user. Use that ID when your own review or customer policy calls for adding or removing the person. Lists are separate for each Space and environment.

Adding requires Reference List to be enabled and an active server-side voice template belonging to your client. An Enrollment ID alone is insufficient: a person with only a device-held template cannot be added by this endpoint and receives no_template_available. Removing an entry is allowed even when Reference List is disabled.

Both helpers run on your backend, hold the space/environment's shared secret, and perform a network request. They use https://api.helix.id by default (HELIX_DEFAULT_API_URL); createAuthUrl uses the portal at https://capsule.helix.id. Override the helpers' baseUrl for a local or alternate API deployment.

import { addToReferenceList, ReferenceListError } from "@helix-id/node";

const options = {
  spaceId: process.env.HELIX_SPACE_ID,
  secret: process.env.HELIX_SECRET,
  enrollmentId: user.helixEnrollmentId, // stored from a verified callback
};

try {
  const entry = await addToReferenceList({
    ...options,
    category: "denied", // your label; Helix does not block this person
    reason: "manual_review",
    customerRef: "CASE-7",
    actor: "support-team",
  });
} catch (error) {
  if (error instanceof ReferenceListError) {
    console.error(error.status, error.code); // upstream HTTP status and error code
  } else {
    throw error; // transport or successful-response JSON parsing failure
  }
}

Remove the person in a separate server action, after your review upholds an appeal:

import { removeFromReferenceList, ReferenceListError } from "@helix-id/node";

try {
  const removal = await removeFromReferenceList({
    spaceId: process.env.HELIX_SPACE_ID,
    secret: process.env.HELIX_SECRET,
    enrollmentId: user.helixEnrollmentId,
    reason: "APPEAL_UPHELD",
  });
} catch (error) {
  if (error instanceof ReferenceListError) console.error(error.status, error.code);
  else throw error;
}

addToReferenceList(options)

A new entry returns HTTP 201. If the person is already listed, the endpoint returns HTTP 200 and their original timestamp/category; it does not update metadata. The enabled-feature and active-template prerequisites still apply to repeated additions.

removeFromReferenceList(options)

Removal returns HTTP 200. Removing an absent entry returns HTTP 404 not_listed, which the helper throws as ReferenceListError.

These reasons record your decision; they do not schedule automatic removal.

Category conventions

category is optional, client-defined text within the character/length limits above. These recommended labels are conventions, not an enum or built-in policies. Custom labels are supported, and the stored label is returned as referenceList.matchedCategory when a new enrollment matches. Your application decides how to act; Helix never blocks or grants privileges based on category.

POST /api/v1/reference-list

The raw endpoint is https://api.helix.id/api/v1/reference-list. Send query parameters, no JSON body. The SDK supplies action, ts, and sig; raw clients must supply them too. Unknown query parameters are rejected.

Sign every transmitted parameter except sig, including all optional metadata, with the selected Space/environment's shared secret. Use the same canonical query encoding as createAuthUrl: sort raw keys; percent-encode each key/value with encodeURIComponent; join key=value pairs with &; compute HMAC-SHA256 and append the lowercase hex digest as sig. Do not sign the already-serialized query string (URLSearchParams encodes spaces differently). Generate a fresh timestamp/signature for each call, keep clocks synchronized, and use HTTPS.

Endpoint HTTP statuses

These are actual HTTP statuses, separate from the voice-auth callback's statusCode. Successful outcomes below describe the operation; the JSON response contains the result fields documented above, without an outcome field.

Business/authentication errors use { error: "code" }; no_template_available also includes a message. Both helpers throw ReferenceListError for any non-2xx response, exposing the upstream .status and backend .code. If the failure body has no usable code (including a non-JSON response), .code is REFERENCE_LIST_REQUEST_FAILED. Transport failures and JSON parsing failures on successful responses propagate unchanged. The helpers do not retry; decide how your server handles each failure rather than forwarding upstream errors to the user automatically.