1. Overview

Kalyax lets you add human verification to your site without accounts, CAPTCHAs, or third-party cookies. The user draws a gesture on a canvas; Kalyax analyses it and issues a signed token. You display the token as a badge — a small image that updates automatically as the token expires.

The simplest integration uses an iframe — Kalyax handles the entire UI and returns the token to your page via postMessage. For full control, use the API directly.

2. Prerequisites

• A page that can run JavaScript
• HTTPS (required for clipboard API and postMessage security)
• No server-side requirement for displaying a badge — badge verification is purely client-side via the image URL
• Optional: a server-side endpoint if you want to verify tokens programmatically before trusting them

3. Integration Flow

Both the iframe and API-direct approaches follow the same underlying protocol steps:

1. Start a bridge session → receive session_id
2. User draws a gesture
3. Submit gesture payload with session_id → receive score
4. Exchange session_id for token → receive verificationToken
5. Store token, display badge

4. Step 1 — Start a Session

Before the user can draw, your page must obtain a session_id. Call this on page load (or just before showing the canvas).

async function startSession() {
  const res = await fetch('https://kalyax.com/api/session/start', {
    method: 'POST',
  });
  const { sessionId } = await res.json();
  return sessionId;
}

const sessionId = await startSession();

5. Step 2 — Capture the Gesture

You must capture pointer events from a canvas element and record each point as { x, y, t, p } where:

• x, y — coordinates in canvas pixels
• t — Date.now() at the time of capture
• p — pressure from PointerEvent.pressure, or 0.5 if unavailable

const strokes = [];
let currentStroke = null;
let startedAt = null;

canvas.addEventListener('pointerdown', e => {
  startedAt = startedAt ?? Date.now();
  currentStroke = { strokeId: strokes.length, points: [] };
  currentStroke.points.push({
    x: e.offsetX, y: e.offsetY,
    t: Date.now(), p: e.pressure || 0.5
  });
});

canvas.addEventListener('pointermove', e => {
  if (!currentStroke) return;
  currentStroke.points.push({
    x: e.offsetX, y: e.offsetY,
    t: Date.now(), p: e.pressure || 0.5
  });
});

canvas.addEventListener('pointerup', () => {
  if (currentStroke) {
    strokes.push(currentStroke);
    currentStroke = null;
  }
});

6. Step 3 — Submit the Drawing

When the user signals completion (e.g. clicks a submit button), POST the gesture payload to /api/verify. Include the sessionId obtained in Step 1.

async function submitDrawing(sessionId, strokes, startedAt) {
  const res = await fetch('https://kalyax.com/api/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      prompt:    'Draw a circle.',  // the prompt you showed the user
      sessionId,
      startedAt,
      endedAt:   Date.now(),
      strokes,
    }),
  });

  if (!res.ok) throw new Error(`Verify failed: ${res.status}`);
  return res.json(); // { isValid, humanLikenessScore }
}

7. Step 4 — Exchange for Token

Immediately after a successful /api/verify response, call /api/token with the same sessionId.

async function getToken(sessionId) {
  const res = await fetch('https://kalyax.com/api/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ sessionId }),
  });

  if (!res.ok) throw new Error(`Token failed: ${res.status}`);
  return res.json();
  // {
  //   verificationToken: "Xk9a...",
  //   verificationUrl:   "https://kalyax.com/v/Xk9a...",
  //   expiresAt:         "2026-04-10T00:00:00+00:00",
  //   isValid:           true
  // }
}

Store verificationToken in your database or user profile. It is the value you will use to construct badge URLs.

8. postMessage Integration (iframe embed)

If you embed https://kalyax.com in an iframe, the page fires a postMessage to the parent window automatically after token issuance.

// Add this to your parent page
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://kalyax.com') return;
  if (event.data?.type !== 'kalyax:verified') return;

  const { token, verificationUrl, isValid, expiresAt } = event.data;
  console.log('Verified!', token);
  // store token, update UI, etc.
});

The message payload:

9. Displaying the Badge

Once you have a verificationToken, construct the badge URL and embed it anywhere.

Web (SVG — recommended)

<a href="https://kalyax.com/v/TOKEN">
  <img src="https://kalyax.com/badge/TOKEN.svg"
       alt="Verified by Kalyax">
</a>

GitHub README (Markdown)

[![Verified by Kalyax](https://kalyax.com/badge/TOKEN.svg)](https://kalyax.com/v/TOKEN)

Email Signature (PNG)

Email clients block pasted HTML. Use your client's insert-image UI:

1. Insert image using the image URL: https://kalyax.com/badge/TOKEN.png
2. Link the image to: https://kalyax.com/v/TOKEN

10. Verifying a Token Server-Side

To confirm a token is valid before taking an action (e.g. accepting a form submission), call /api/check/{token} from your server.

// Node.js example
async function checkToken(token) {
  const res = await fetch(
    `https://kalyax.com/api/check/${token}`
  );
  const data = await res.json();
  return data.valid && data.signatureValid && !data.expired;
}

Only trust a token if all three conditions are met: valid: true, signatureValid: true, expired: false.

11. Error Handling

Sessions expire after 15 minutes. If the user takes longer than 15 minutes between starting and submitting, call /api/session/start again to obtain a fresh session.

12. Complete Example

The following is a minimal end-to-end integration using the Kalyax API directly.

// 1. On page load — start bridge session
let sessionId = null;
let strokes = [];
let startedAt = null;

async function init() {
  const res = await fetch('/api/session/start', { method: 'POST' });
  ({ sessionId } = await res.json());
}

// 2. Canvas gesture capture
canvas.addEventListener('pointerdown', e => {
  startedAt = startedAt ?? Date.now();
  currentStroke = { strokeId: strokes.length, points: [] };
  currentStroke.points.push({ x: e.offsetX, y: e.offsetY, t: Date.now(), p: e.pressure || 0.5 });
});
canvas.addEventListener('pointermove', e => {
  if (currentStroke)
    currentStroke.points.push({ x: e.offsetX, y: e.offsetY, t: Date.now(), p: e.pressure || 0.5 });
});
canvas.addEventListener('pointerup', () => {
  if (currentStroke) { strokes.push(currentStroke); currentStroke = null; }
});

// 3. On submit button click
submitBtn.addEventListener('click', async () => {
  // Step 3: submit drawing
  const verifyRes = await fetch('https://kalyax.com/api/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      prompt: 'Draw a circle.', sessionId,
      startedAt, endedAt: Date.now(), strokes,
    }),
  });
  if (!verifyRes.ok) { return showError('Verification failed'); }

  // Step 4: exchange for token
  const tokenRes = await fetch('https://kalyax.com/api/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ sessionId }),
  });
  if (!tokenRes.ok) { return showError('Token issuance failed'); }

  const { verificationToken, verificationUrl } = await tokenRes.json();

  // Step 5: display badge
  badgeEl.innerHTML = `
    <a href="${verificationUrl}">
      <img src="https://kalyax.com/badge/${verificationToken}.svg"
           alt="Verified by Kalyax">
    </a>`;

  // Refresh session for next verification
  sessionId = null; strokes = []; startedAt = null;
  await init();
});

init(); // start on load