Skip to main content
Novi Kvadrat Developers
On this page

Keys

Generate an Ed25519 key pair, register the public key in the Partner Portal, and send the key id with every request.

Every request is signed with an Ed25519 private key that never leaves your servers. You register only the public key; we store only public keys. There are no shared secrets on the inbound side.

Generate a key pair#

With OpenSSL:

sh
openssl genpkey -algorithm ed25519 -out nk-private.pem
openssl pkey -in nk-private.pem -pubout -out nk-public.pem

With Node (≥ 20):

js
import { generateKeyPairSync } from 'node:crypto'
const { publicKey, privateKey } = generateKeyPairSync('ed25519')
console.log(publicKey.export({ format: 'pem', type: 'spki' }))
// keep privateKey.export({ format: 'pem', type: 'pkcs8' }) in your secret store

Or with the reference client:

sh
node nk-partner.mjs keygen --out=nk

Register the public key#

In the Partner Portal, open Integration › Apps and keys, pick the app and press Register key. Paste the public key in either form:

  • raw base64 of the 32 public-key bytes, e.g. RXFUSrDp7RaeGIkOOA8m0QFuuGeC3W+Ks1xqNQLglU4= (that one is the published test key and is refused);
  • PEM (SPKI), starting -----BEGIN PUBLIC KEY-----.

Add an optional label (up to 80 characters, e.g. export-server-1). The key expires 365 days after registration (there is no picker).

The Partner Portal answers:

Code Meaning
public_key_invalid not an Ed25519 public key (or the published test key)
public_key_in_use this key is already registered
key_limit_reached the app already has 2 active keys: revoke one first
terms_not_accepted a partner admin must accept the current partner terms first

Who may register: admins on any app; developers on sandbox apps only. Live keys are admin-only.

The key id#

On success you get a key id: nkp_sandbox_ or nkp_live_ followed by 16 characters (lower-case Crockford base32, e.g. nkp_sandbox_7f3k9q2m4x8c1v6b). It is not a secret. Send it in the NK-Key-Id header of every request. The Partner Portal also shows the key's fingerprint, sha256: and the first 16 hex characters of the SHA-256 of the public key, so you can tell keys apart.

Rules#

  • At most 2 active keys per app — enough to rotate without downtime.
  • A key is active or revoked. Revoking is immediate and permanent; a revoked key answers 401 key_invalid.
  • A key past its 365 days answers 401 key_expired. We warn 30 days ahead (overview, webhook key.expiring, email to admins).
  • A sandbox key works only with sandbox apps and sandbox connection codes; a live key only with the live app.

Last updated