Node.js library — Voidhash Docs

The mobile SDKs decide what to show on the device. They cannot protect anything a customer can reach by calling your API directly, such as an export endpoint or a paid model. Those checks belong on your server, and this library is how you make them.

@voidhash/node is a typed client for the Voidhash REST API. It authenticates every request with a project secret key, and acts on the project the key belongs to.

Install the SDK

The Node SDK is published to pkg.voidha.sh from every change, before it is released on npm. Install the newest build:

npm install @voidhash/node@https://pkg.voidha.sh/voidhash-node/main

For production, pin a build, so every deploy installs the same SDK. The version of an installed build ends with -g and its short commit hash, as in 0.0.1-alpha.1-g83f7412; install that build with https://pkg.voidha.sh/voidhash-node/83f7412, using your hash. Your lockfile then records exactly that build. npm install @voidhash/node installs an early preview that predates this guide.

The package needs Node 18 or newer with a global fetch. If you load it with require(), you also need Node 20.19 or newer, or Node 22.12 or newer. The CommonJS build loads the ESM-only effect package, and only those versions can do that. Loading it with import has no such constraint.

Create a secret key

In Studio, open Settings → API keys and create a secret key. The raw value is shown only once.

Store the key in an environment variable or your secret manager. A secret key grants full access to the project. Never put it in a mobile app, a web bundle, or a repository.

Create the client

Create one client with your secret key and export it for the rest of your server to use.

server/voidhash.ts

import { createVoidhashSdk } from "@voidhash/node";

export const voidhash = createVoidhashSdk({
  secretKey: process.env.VOIDHASH_SECRET_KEY!,
});

createVoidhashSdk accepts these options.

Option	Default	Description
`secretKey`	none	Required. The SDK sends it as `Authorization: Bearer <secretKey>`.
`projectId`	the key's project	The project every call acts on. Set it to skip looking the project up.
`baseUrl`	`https://api.voidhash.com`	Overrides the API origin. The scheme must be `http:` or `https:`.
`headers`	`{}`	Extra headers the SDK adds to every request from this client.

createVoidhashSdk validates its options right away rather than on the first request, and makes no request itself. It throws VoidhashNodeConfigurationError when secretKey or projectId is blank, baseUrl is invalid, there is no global fetch, or headers contains Authorization or x-secret-key in any casing.

A secret key belongs to one project, so you never pass the project's id to a method. Without projectId, the SDK reads the key's project from GET /api/v1/session on the first call that needs it and keeps it for the client's lifetime. When the credential can use several projects, set projectId; otherwise those calls reject with VoidhashNodeConfigurationError.

With the client configured, continue with checking access or receiving webhooks.

Effect entrypoint

The SDK also ships an Effect entrypoint. Effect is the TypeScript library the SDK depends on internally, and this entrypoint exposes every method as an Effect value instead of a Promise.

Import from @voidhash/node/effect to get the Effect-based client.

import { createVoidhashSdk } from "@voidhash/node/effect";

const voidhash = createVoidhashSdk({ secretKey: process.env.VOIDHASH_SECRET_KEY! });

const program = voidhash.entitlements.hasActivePerk({
  distinctId: "user_123",
  perkSlug: "premium",
});

This entrypoint exposes Effect types across the package boundary, so your app must resolve to the same effect instance and version the SDK depends on. Effect v4 is still in beta, and its types are not stable across releases. The default entrypoint has no such constraint because it returns plain Promises.

The webhook helpers do not use Effect. Both entrypoints export them identically.