API keys

An API key does two things: it authenticates your server’s requests, and it carries the settings of every verification created with it (which steps the person goes through, how long data is kept, where webhooks go).

Create a key

1. Sign in to the operator console with your organization’s main login (only main logins see API keys).
2. Open API keys → New API key.
3. Enter a name that says where the key is used, for example Shop – production or Hotel check-in – staging.
4. Enter the webhook URL: the HTTPS address on your server that receives results (you can add or change it later).
5. Choose the flow and the other settings (Configure a key).
6. Create the key. The console shows two values once:
   • the API key (vk_live_…), sent with every API request;
   • the webhook signing secret (whsec_…), used to check that webhooks really come from ZetaID (Get the result).

Copy both into your server’s secret store (environment variables, a vault, your platform’s secret manager). ZetaID keeps only a fingerprint of the API key and cannot show it again; if it is lost, create a new key.

Use a key

Send the key in the X-SDK-Key header of every API request:

POST /api/v1/verifications HTTP/1.1
Host: verify.zetaid.com
X-SDK-Key: vk_live_8c1f…
Content-Type: application/json

A missing, wrong or deactivated key gets 401 SDK_KEY_INVALID.

Never in a browser or an app

Anyone who has the key can create verifications billed to your organization and read results. Don’t put it in JavaScript that runs in the browser, in a mobile app, or in a repository. The API refuses requests that come from a web page (403 SERVER_SIDE_ONLY).

One key per use

Create a separate key for every site, app or environment. Each key has its own flow, retention and webhook URL, and the operator console shows which key created each verification. A test environment gets its own key with its own webhook URL.

Replace a key

To replace a key (a suspected leak, a staff change):

1. Create a new key with the same settings.
2. Deploy it to your server.
3. In API keys, deactivate the old key. Verifications that are already running continue; new requests with the old key are refused.

A key that never created a verification can be deleted; any other key can only be deactivated, so its verifications keep their history.

The webhook signing secret

Every key has its own signing secret. Rotate signing secret on the key replaces it and shows the new one once; from that moment ZetaID signs this key’s webhooks (including retries of earlier ones) with the new secret, so update your server right away.

Keys created before signing secrets existed show Shared platform signature: use Create signing secret on them to give them their own.