Authentication

API keys

Every SmartAI Assessment account has two keys:

Key	Header	Where it’s used
API key	`x-api-key`	Every request — identifies your organisation
Secret key	Used for HMAC signing	Every request — proves the request wasn’t tampered with

Never expose your secret key in browser code or version control. Set both keys as environment variables on your server only.

ASSESSMENT_API_KEY=VFN_TEST_24D67D244DC03E7691654336913EF84B
ASSESSMENT_SECRET_KEY=VFN_SK_TEST_2BA620C5C940D87AF80700B4EE85B4621F516BE8C4F89563

Live vs test environments

The API key prefix determines which environment you’re in:

Prefix	Environment	Notes
`VFN_TEST_`	Test / staging	No real emails sent, safe to experiment
`VFN_LIVE_`	Live / production	Real candidate emails, full proctoring

HMAC-SHA256 signing

The Backend SDK signs every request automatically. You never need to do this manually. This section is for reference only.

Signature construction

payload = "METHOD:PATH:TIMESTAMP:SORTED_BODY_JSON"

Examples:
  GET:/api/v1/webhook/events:1717200000000:
  POST:/api/v1/sessions:1717200000000:{"users":[{"email":"a@b.com","name":"A"}]}

Rules:

Body keys sorted alphabetically (nested keys too)
Empty body → empty string (not {})
Timestamp is Unix milliseconds as a string

Headers sent on every request

x-api-key:   VFN_TEST_24D67D244DC03E7691654336913EF84B
x-signature: <hmac-sha256-hex-digest>
x-timestamp: 1717200000000

Signing reference

import crypto from 'crypto';

function buildSignature(
  method: string,
  path: string,
  body: object | null,
  secretKey: string
): { signature: string; timestamp: string } {
  const timestamp = Date.now().toString();

  const sortedBody = body
    ? JSON.stringify(body, Object.keys(body).sort())
    : '';

  const payload = `${method}:${path}:${timestamp}:${sortedBody}`;

  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(payload)
    .digest('hex');

  return { signature, timestamp };
}

import hashlib
import hmac
import json
import time

def build_signature(method, path, body, secret_key):
    timestamp = str(int(time.time() * 1000))

    sorted_body = (
        json.dumps(body, sort_keys=True, separators=(",", ":"))
        if body else ""
    )

    payload = f"{method}:{path}:{timestamp}:{sorted_body}"

    signature = hmac.new(
        secret_key.encode(),
        payload.encode(),
        hashlib.sha256,
    ).hexdigest()

    return {"signature": signature, "timestamp": timestamp}

Timestamp window

Environment	Window
Production	5 minutes
Development	30 minutes

Requests outside the window are rejected with 403 Forbidden.

SDK initialisation

Instantiate once per request (or share a single instance per server process):

const AssessmentClient = require('@recordorg/smartai-assessment-backend');

const client = new AssessmentClient({
  apiKey:    process.env.ASSESSMENT_API_KEY,
  secretKey: process.env.ASSESSMENT_SECRET_KEY,
});

from smartai_assessment_backend import AssessmentClient
import os

client = AssessmentClient(
    api_key=os.getenv("ASSESSMENT_API_KEY"),
    secret_key=os.getenv("ASSESSMENT_SECRET_KEY"),
)

The SDK reads both keys and attaches the correct headers and HMAC signature to every outgoing request — you do not pass keys to the frontend or to candidates.

Getting Started

REST API

Backend SDK

Frontend SDK

Webhook & Data

API keys

Live vs test environments

HMAC-SHA256 signing

Signature construction

Headers sent on every request

Signing reference

Timestamp window

SDK initialisation

​API keys

​Live vs test environments

​HMAC-SHA256 signing

​Signature construction

​Headers sent on every request

​Signing reference

​Timestamp window

​SDK initialisation

API keys

Live vs test environments

HMAC-SHA256 signing

Signature construction

Headers sent on every request

Signing reference

Timestamp window

SDK initialisation