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.

Install the SDK

Install the package from npm.

npm install @voidhash/node

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 the `x-secret-key` header.
`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. It throws VoidhashNodeConfigurationError when secretKey is blank, baseUrl is invalid, there is no global fetch, or headers contains x-secret-key in any casing.

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.