Authentication

Use an API key in the apiKey header to authenticate requests to Niva. Create keys in the Niva dashboard under Settings › API Keys.

Choose the right credentials

Credential	Use
Private API key (`nt_…`)	Server-side requests, including creating submissions and running verification. Keep it on your server.
Public API key (`ntpub_…`)	The Public Documents API and embeddable widgets. It can be used in your frontend.
Submission token (`token`)	Grants access to one submission through the Public Documents API or widgets. Use it together with a public API key.

The submission token is returned by Create new submission and Get submission. It expires 24 hours after issue. Call Get submission from your backend for a fresh token, and give it only to the user who should access that submission.

Send a request

For example, call List submissions from your server:

The header name is case-insensitive and has no hyphen. Use the key issued for the environment you are calling.

Handle authentication errors

A missing, invalid, or deactivated API key returns 401 Unauthorized. Sending a public key to a private endpoint, or a private key to a public endpoint, also returns 401:

{
  "errors": ["401 Unauthorized"]
}

An invalid or expired submission token returns 401 with a different message:

{
  "errors": ["Invalid token."]
}

Rotate keys

Create a new key, update your integration, then deactivate the old key in Settings › API Keys. Never put private keys in browser code or public repositories.

Continue with Getting started.

Authentication

Choose the right credentials#

Send a request#

Handle authentication errors#

Rotate keys#

Choose the right credentials

Send a request

Handle authentication errors

Rotate keys