KyneticID integration: development plan for your team

This is the step-by-step plan for integrating KyneticID face verification into your product, from the first day to production. Follow the phases in order. Each step says what to do and how to confirm it is done.

The API reference is at https://custonboard-kyneticid.oddinson.com/api-docs. It lists every transactions API parameter, response field and error, the exact request KyneticID sends to your backend for each result, and a Postman collection to download. This plan links to it wherever field-level detail is needed.

What you build

Every decision that grants access is made on what your backend receives through the callback, never on what the page receives. The page receives only pass or fail and a sentence to show the person.

Two environments

KyneticID gives you two kinds of api_key. The scanner package selects the environment from the key; there is nothing to configure in the page.

Each key has its own callback URL, callback signing secret, API secret and allowed website origins. Faces registered with the test key do not exist in production.

Credentials

• Do not use the api_key to authorise anything. The transactions API refuses it.
• The signing secret and the API secret must never reach a browser, a mobile app, a repository or a log. Keep them in your backend's secret store.
• KyneticID shows each secret once. A lost secret is replaced, not recovered.

Phase 0: Prepare

Step 0.1: GitHub accounts

The scanner packages are private packages in KyneticID's GitHub organisation, kyneticID. GitHub lets only members of that organisation read them, so every developer who installs them needs a personal GitHub account, which KyneticID invites into kyneticID. You do not create a GitHub organisation of your own.

As members, your accounts can read the two scanner packages and nothing else: they have no access to any repository and cannot create one. Members of the organisation can see the usernames of its other members.

• Developers without an account create one, free, at https://github.com/signup.
• CI (continuous integration) means a server that installs, builds and deploys your code automatically, such as GitHub Actions, GitLab CI or Jenkins. If one installs the packages, create a dedicated GitHub account for it rather than using a person's. Without CI, skip every CI item in this plan.

Done when: you have the GitHub username of every developer, and of the CI account if you use CI.

Step 0.2: Send KyneticID these details

The scanner works only on origins KyneticID has allowed. A page on any other origin loads, but every scan fails at the bot check.

Step 0.3: Receive from KyneticID

• A GitHub invitation to the kyneticID organisation, by email, for each username.
• The test api_key, in the clear.
• The test key's callback signing secret and API secret, through a secret-sharing channel. Store them in your backend's secret store at once.
• Confirmation that your origins are allowed.

The production key and its secrets come in Phase 7.

Done when: every developer has the invitation email, and the test key and its two secrets are stored.

Phase 1: Get the package

Step 1.1: Accept the invitation

Each person opens the invitation email and accepts it, signed in to GitHub as the account it was sent to. Without the email, open https://github.com/orgs/kyneticID/invitation while signed in. An invitation expires after 7 days; ask KyneticID to send a new one if it does.

Done when: kyneticID is listed at https://github.com/settings/organizations for that account.

Step 1.2: Create a token

Each developer, and the CI account if you use CI, creates a token with the read:packages scope. Either:

• GitHub CLI (https://cli.github.com, for macOS, Windows and Linux):

  gh auth login
  gh auth refresh -h github.com -s read:packages
  

  Run gh auth login only if gh is not signed in yet. Then put the token in the environment variable NODE_AUTH_TOKEN for the terminal you install from:

  Terminal	Command
  macOS or Linux (bash, zsh)	export NODE_AUTH_TOKEN=$(gh auth token)
  Windows PowerShell	$env:NODE_AUTH_TOKEN = gh auth token
  Windows Command Prompt	for /f %i in ('gh auth token') do set NODE_AUTH_TOKEN=%i

  These last for that terminal session. To keep it: on macOS or Linux add the export line to your shell profile (~/.zshrc or ~/.bashrc); on Windows run setx NODE_AUTH_TOKEN "<the token>" once, which applies to terminals opened afterwards.

• Personal access token (classic): GitHub → profile picture → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic). Select only read:packages, set an expiration date, and copy the token at once; GitHub does not show it again. Set it as the environment variable NODE_AUTH_TOKEN the same way: export NODE_AUTH_TOKEN=<the token> (macOS, Linux), $env:NODE_AUTH_TOKEN = "<the token>" (PowerShell), set NODE_AUTH_TOKEN=<the token> (Command Prompt), or setx on Windows to keep it. Use this kind for CI, stored as a CI secret named NODE_AUTH_TOKEN.

Fine-grained personal access tokens cannot read GitHub Packages.

Done when: in the terminal you install from, this prints set (do not print the token itself):

Step 1.3: Point npm at the registry

Create .npmrc next to the package.json of your React project:

@kyneticid:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

Commit this file. It holds no secret: the token stays in the environment variable. npm reads ${NODE_AUTH_TOKEN} on macOS, Windows and Linux alike.

Step 1.4: Install

npm install @kyneticid/react

@kyneticid/sdk is installed with it. React 18 or newer is required.

Done when: npm ls @kyneticid/react shows version 1.1.0 or later. If it fails with 401 or 403, see the troubleshooting table at the end.

Step 1.5: CI (only if you use CI)

Store the CI account's token as the CI secret NODE_AUTH_TOKEN and expose it as an environment variable to the install step. The committed .npmrc does the rest.

Done when: a CI build installs the package.

Phase 2: The scanner in your page (test key, on your computer)

Step 2.1: Page requirements

• HTTPS, or localhost. Browsers allow the camera only on HTTPS pages and on localhost. The page's origin must be one of those allowed in step 0.2.

• No iframe is needed. The scanner is a component inside your own page. Only if your page is itself shown inside an iframe on another page does that iframe need allow="camera", because browsers block the camera in an iframe without it. If your site sends a Permissions-Policy header, it must allow camera for the page.

• Next.js and other server-rendering frameworks: the component is a client component (the package declares "use client") and renders nothing on the server.

• Content-Security-Policy. If your site sends one, allow the scanner's hosts:

  Host	Environment	What the scanner loads or sends
  https://demo-api-kyneticid.oddinson.com	test key	the scan session (requests from the browser)
  https://api-kyneticid.oddinson.com	production key	the scan session
  https://demo-cdn-kyneticid.oddinson.com	test key	the on-device models and their runtime (scripts and WebAssembly)
  https://cdn-kyneticid.oddinson.com	production key	the on-device models and their runtime

  The scanner also uses four hosts outside KyneticID's domain, for both keys: the upload of the captured pictures (PUT), the bot check (script and frame), and the face-tracking runtime (scripts and WebAssembly) and model. KyneticID sends you these four on request.

  The on-device models run as WebAssembly, which a script-src directive blocks unless it includes 'wasm-unsafe-eval'. To confirm a policy, run one scan with the browser's developer console open: a blocked request is reported there as a Content-Security-Policy violation.

Step 2.2: Add the component

import { KyneticID } from '@kyneticid/react';

export function VerifyFace({ user }) {
  return (
    <KyneticID
      apiKey={process.env.NEXT_PUBLIC_KYNETICID_API_KEY}
      referenceId={user.id}
      onResult={(result) => showOutcome(result.decision, result.message)}
      onError={(error) => showError(error.message)}
    />
  );
}

Read the api_key from your build configuration, so that test and production builds use their own key. The environment variable name above is an example.

The component brings its own camera view, instructions and styling. The camera starts when the person presses the scanner's start button. The person has 60 seconds from the start to line up with the camera and complete the movements, with 8 on-screen reminders; the whole scan, upload and judgement included, must finish within 120 seconds. The failure screen has a "Try again" button, which starts a new scan.

Changing apiKey, faceId or referenceId restarts the scanner. Do not pass apiUrl: the package sets the address from the key.

Done when: the page shows the scanner, the camera starts on the button, and a scan on your computer ends with onResult called.

Step 2.3: Handle onResult

onResult receives:

{ "session_id": "6b1f0c2a9e4d7731", "decision": "pass", "reason_code": "OK", "message": "Verified.", "elapsed_ms": 4180 }

Use it to tell the person how it went. Grant nothing until your backend has the result callback for that session_id.

Step 2.4: Handle onError

error.message is Server error (<HTTP status>) when the service refused to start or run the session, or Server error (<reason>) with a short reason when the verification step failed:

onError is also called when the camera cannot start (permission refused, no camera) and when the upload fails. In every case the scanner already shows the person a message; use onError for your own logging or to offer another way forward.

Phase 3: The callback endpoint (test key)

Step 3.1: Build the endpoint

For every scan that reaches a verdict, pass or fail, KyneticID sends one POST to the key's callback URL. A scan abandoned before a verdict sends nothing.

POST /kyneticid/callback HTTP/1.1
content-type: application/json
user-agent: KyneticID-Webhooks/1.0
webhook-id: 6b1f0c2a9e4d7731
webhook-timestamp: 1792137601
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "type": "verification.completed",
  "timestamp": "2026-10-16T08:00:00.000Z",
  "data": {
    "session_id": "6b1f0c2a9e4d7731",
    "reference_id": "user-123",
    "decision": "pass",
    "reason_code": "OK",
    "face_id": "f_3c9a1e2b7d4f6a80.Xk2pQ7vN0aLm4RtY8wZc1bHs6uJe9dFg",
    "is_new": true,
    "similarity": null,
    "possible_duplicates": [],
    "images": [
      {
        "tag": "neutral",
        "url": "https://demo-media-kyneticid.oddinson.com/6b1f0c2a9e4d7731/01.jpg?exp=1792138501&sig=q8Zr2mN5xT0bVc7LkP3sHw9YdJ4aFe6gUi1oRtQyXzA",
        "expires_at": 1792138501000
      }
    ]
  }
}

The endpoint does these, in order:

1. Verify the signature over the raw body, before parsing it. Reject the request (for example with 401) if it does not verify, or if webhook-timestamp is more than 5 minutes from your clock. The standardwebhooks library does both; it is published for Node (npm), Python (PyPI), Ruby (RubyGems), Rust (crates.io), Java and Kotlin (Maven Central com.standardwebhooks:standardwebhooks), C# (NuGet StandardWebhooks.StandardWebhooks) and Go.
2. Process each webhook-id once. It equals data.session_id. Store it, and ignore a request whose webhook-id you have already processed.
3. Answer with any 2xx status within 15 seconds, for example 204. The body of your answer is not read. Do slower work, such as downloading the pictures, after answering.
4. Store the result against the user named by data.reference_id. On a pass, store data.face_id with that user: it is needed for every repeat check of this person (Phase 4).
5. Download the pictures you want to keep. Each url works for 15 minutes from when the request was sent (expires_at, Unix milliseconds). After that, read the transaction again for new links (Phase 5).
6. Ignore other event types. If type is not verification.completed, answer 2xx and do nothing.

Do not use user-agent to decide that a request is genuine: anyone can send it. Only webhook-signature proves it.

Node (Express)

import express from 'express';
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.KYNETICID_SIGNING_SECRET);   // whsec_...
const app = express();

app.post('/kyneticid/callback', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers);   // throws if forged, altered or stale
  } catch {
    return res.sendStatus(401);
  }
  await saveResult(req.headers['webhook-id'], event.data);   // idempotent on webhook-id
  res.sendStatus(204);
});

Python (Flask)

import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook

wh = Webhook(os.environ["KYNETICID_SIGNING_SECRET"])   # whsec_...
app = Flask(__name__)

@app.post("/kyneticid/callback")
def kyneticid_callback():
    headers = {k.lower(): v for k, v in request.headers.items()}
    try:
        event = wh.verify(request.get_data(), headers)
    except Exception:
        return "", 401
    save_result(headers["webhook-id"], event["data"])   # idempotent on webhook-id
    return "", 204

Without the library, the whole algorithm is:

1. key = base64-decode of the signing secret with the whsec_ prefix removed.
2. content = webhook-id + . + webhook-timestamp + . + the raw body.
3. expected = base64(HMAC-SHA256(key, content)).
4. webhook-signature is a space-separated list of v1,<signature> entries. Accept if any v1 signature equals expected, compared in constant time.
5. Reject if webhook-timestamp is more than 5 minutes from your clock.

Every field of the request is described in the API reference under Result callback.

Step 3.2: Make the test endpoint reachable

KyneticID sends the callback from the internet, so the test key's callback URL must be a public HTTPS address. A backend running on a developer's computer is not reachable: deploy the endpoint to your staging backend, or expose it through an HTTPS tunnel, and send that URL to KyneticID (step 0.2).

Delivery rules:

• One attempt. If the endpoint is down, answers with a non-2xx status, takes longer than 15 seconds, redirects, or cannot be reached, the callback is recorded as failed and not sent again.
• Redirects are not followed: the registered URL must answer directly.

Step 3.3: Test the endpoint without a scan

1. Download the Postman collection from https://custonboard-kyneticid.oddinson.com/api-docs and import it into Postman.
2. In the collection's Variables tab, fill in callbackUrl (your test callback URL) and callbackSigningSecret (the test key's whsec_ secret), and save.
3. Run Test your callback. It sends a sample result signed exactly as KyneticID signs one.

Done when: your endpoint verifies the sample and answers 2xx, and refuses it after you replace one character in the middle of callbackSigningSecret (keep the whsec_ prefix). Postman signs the body again on every send, so editing the body does not test refusal.

Step 3.4: Read the result correctly

One face, one face_id. On a first check (no faceId passed), the face is compared with every face already registered under your key's account, never another customer's:

• 0.70 or above: the same person. No new face_id is created; you receive the face_id this person was first registered with, is_new: false, and the similarity. If reference_id names a different user of yours, the same person is opening a second account.
• 0.55 to 0.70: a new face_id is created, and possible_duplicates lists who it resembles.
• Below 0.55: a new person.

Identical twins, and sometimes close lookalikes, score above 0.70 and receive one face_id. A newly registered face takes a few minutes to become searchable: the same face registered again without its face_id within those minutes receives a second face_id. Passing the stored face_id for every later check (Phase 4) prevents this.

Done when: a real scan on your page reaches your endpoint, verifies, and stores the face_id against the right user.

Phase 4: Repeat checks

For a returning user:

1. Your backend looks up the face_id it stored for that user.
2. Your backend gives it to your page.
3. Your page passes it to the scanner:

<KyneticID apiKey={apiKey} faceId={storedFaceId} referenceId={user.id} onResult={showOutcome} />

The result arrives at your backend as in Phase 3, with is_new: false and a similarity. A different face fails with FACE_ID_MISMATCH. A face_id that was altered, or belongs to another customer, is refused before the scan starts. A face_id works only for the account and environment that issued it: a test-key face_id does not work with the production key.

Done when: the same person passes a repeat check, and another person fails it with FACE_ID_MISMATCH.

Phase 5: The transactions API

Step 5.1: Call it from your backend

Call it from your backend only. Browsers are not allowed to send the Authorization header to it, and an API secret in a web page can be read by anyone.

• Address: the key's transactions API address (see "Two environments").
• Header on every request: Authorization: Bearer sk_...

Only scans that reached a verdict are returned. Every response carries newly signed picture links, valid for 15 minutes.

Dates and times

• Every time in a response is Unix milliseconds (for example created_at).
• from and to are dates written YYYY-MM-DD, read as UTC days. The API takes no time zone and does not convert. Give both or neither; the range may cover at most 31 days, both ends included. Without them, the last 31 UTC days are returned, today included.
• Example for Malaysia (UTC+8): to read every scan of 16 October 2026 in Malaysia time (2026-10-15 16:00:00 UTC to 2026-10-16 15:59:59 UTC), request from=2026-10-15&to=2026-10-16 and keep the transactions whose created_at is from 1792080000000 up to but not including 1792166400000.

Errors: 400 with error naming the parameter at fault, 401 unauthorized (missing, wrong or revoked API secret, or the api_key is off), 404 not_found, 500. More than 600 requests in 10 seconds from one IP address, counting the API and the picture links together, receive 429 with a body that is not JSON: wait 10 seconds before trying again.

Every parameter, field and error, with examples: https://custonboard-kyneticid.oddinson.com/api-docs. The reference shows the production address; with the test key, use https://demo-api-kyneticid.oddinson.com.

Step 5.2: Try it in Postman

1. In the collection's Variables tab, fill in apiSecret (the key's sk_ secret). For the test key, also change baseUrl to https://demo-api-kyneticid.oddinson.com; the collection is preset to the production address. Save.
2. Run List transactions first: it fills in a session id, the next page cursor and a picture link for the other requests.
3. Run Count transactions, Get a transaction and Get a picture.

Done when: each request answers 200, and Get a picture returns an image.

Step 5.3: Build reconciliation

Because a callback is sent only once, run a scheduled job that lists recent transactions and processes every one whose callback_status is not delivered (failed, pending, not_configured or null) as if its callback had arrived. Use the same idempotent handling as the callback (keyed on session_id).

Done when: a scan made while your callback endpoint was stopped is found and processed by the job.

Step 5.4: Picture links

• Open each images[].url exactly as received, from your backend or in an <img> tag. No credential is needed: the signature in the link is the permission, so treat a link like the picture itself and do not pass it on.
• A link works for 15 minutes, then answers 403 expired. Do not store links; store the pictures you need to keep.
• Do not build or change a link: any change answers 403 bad_signature.

Phase 6: Test on your test site

Deploy your page and backend to your test site, still with the test key. Then confirm each item:

Phase 7: Go live

1. Ask KyneticID for the production key and its two secrets, if you do not have them yet. Confirm the production origin(s), the production callback URL and the monthly quota (step 0.2).
2. Store the production secrets in your production backend's secret store: the production callback signing secret and the production API secret.
3. Switch the production build:
   • the page uses the production api_key;
   • the backend verifies callbacks with the production signing secret;
   • the backend calls https://api-kyneticid.oddinson.com with the production API secret;
   • your Content-Security-Policy allows the production hosts (step 2.1).
4. Repeat checks 2 to 6, 9 and 10 of Phase 6 on the production site.
5. Replace any secret that was exposed during development (Phase 8).

Done when: a scan on the production site passes, its callback is delivered, and the face_id is stored.

Phase 8: Operations

Reference: reason codes

Every scan that starts uses one scan of the key's monthly quota, whether it passes or fails.

Reference: troubleshooting

Reference: limits to design around

• A result callback is sent once and never retried; reconcile with the transactions API (step 5.3).
• Picture links last 15 minutes; store the pictures you need.
• A new face becomes searchable for duplicate matching only after a few minutes.
• Every scan that starts uses one scan of the key's monthly quota, whether it passes or fails.
• 600 requests per 10 seconds per IP address, across the API and the picture links.
• The scanner works only on origins KyneticID has allowed for that key.