Authentication — Voidhash Docs

Every request to the Voidhash API carries a credential. Voidhash has three programmatic credential types, each meant for a different kind of caller. Use the narrowest one that fits.

Credential	Header	Use
User API key	`x-api-key`	CLI and tools acting as a signed-in user across projects.
Project secret key	`x-secret-key`	Server-to-server requests for one project, including event capture.
Publishable key	`x-publishable-key` + `x-distinct-id`	Official SDKs and distributed clients.

Project secret keys

A project secret key authorizes your backend to act on one project. Send it in the x-secret-key header:

curl https://api.voidhash.com/api/v1/persons \
  -H "x-secret-key: $VOIDHASH_SECRET_KEY"

Never expose a secret key

A project secret key grants broad access to the project. Do not put it in a mobile app, web bundle, public repository, or analytics event property. Rotate it immediately after exposure.

User API keys

A user API key acts as a signed-in user. It is useful for local tools and automation that need access to more than one project. Send it in the x-api-key header:

curl https://api.voidhash.com/api/v1/auth/session \
  -H "x-api-key: $VOIDHASH_API_KEY"

The CLI obtains and stores this credential for you when you run voidhash-cli auth login.

Publishable keys

A publishable key is safe to ship inside an app. It only authorizes the device-facing SDK surface, and it must be paired with a customer identity in the x-distinct-id header:

curl https://api.voidhash.com/api/v1/sdk/person \
  -H "x-publishable-key: vh_pk_..." \
  -H "x-distinct-id: user_123"

The official SDKs also send platform and client metadata that these endpoints require. Prefer the SDK over calling them directly.

Verify a credential

Call GET /api/v1/auth/session with any credential. The response shows how the key was resolved and which project it can access.

A valid key can still receive a 403 when it lacks permission for a specific operation.

Event capture

The event capture endpoints, /i/v1/capture and /i/v1/batch, accept either a secret key or a publishable key. Which one you send depends on where the request comes from.

From a backend, send the project secret key as x-secret-key. No x-distinct-id header is needed, because each event carries its own distinct_id.

From a distributed client that cannot hold a secret, send the publishable key as a token field in the JSON body instead.

Send one or the other. When both are present, the body token wins. See Event Capture for request examples.