@kolaylogin/backend

Framework-agnostic server-side helpers: verify session JWTs, parse cookie headers, validate webhook signatures, and call the payments surface.

Copy this quickstart guide as a prompt for LLMs to implement KolayLogin in your application.

KolayLoginBackendClient

import { KolayLoginBackendClient } from '@kolaylogin/backend';

const kolay = new KolayLoginBackendClient({
  // baseUrl defaults to https://api.kolaylogin.com
  issuer: process.env.KL_JWT_ISSUER,
});

// Verify by raw token
const claims = await kolay.verifySessionJwt(token);

// Or pass any request-like shape; reads __session from cookies
const claimsFromReq = await kolay.getSessionFromRequest(req);

verifySessionJwt(token, options)

Standalone helper if you don't want the class wrapper.

import { verifySessionJwt } from '@kolaylogin/backend';

// jwksUrl defaults to https://api.kolaylogin.com/.well-known/jwks.json
const claims = await verifySessionJwt(token, {
  clockToleranceSeconds: 5,
});

Returns a typed SessionClaims: sid, sub, env, org, org_role, iat, exp.
Throws if the token is expired, malformed, or not signed by a key in the JWKS.

Cookie helpers

import { parseCookieHeader, getSessionJwtFromCookieHeader } from '@kolaylogin/backend';

const jar = parseCookieHeader(req.headers.cookie);
const jwt = getSessionJwtFromCookieHeader(req.headers.cookie);

requireSession(req, opts)

Promise-returning helper that throws on failure — use in Hono/Koa-style middleware.

import { requireSession } from '@kolaylogin/backend';

app.use(async (ctx, next) => {
  const claims = await requireSession({ headers: ctx.req.header() }, {
    jwksUrl: "https://api.kolaylogin.com" + '/.well-known/jwks.json',
  });
  ctx.set('auth', claims);
  await next();
});

verifyWebhookSignature()

All webhooks are signed with HMAC-SHA256 over `${timestamp}.${body}` and base64url-encoded. This helper verifies and rejects replays older than 5 minutes (configurable).

import { verifyWebhookSignature, assertWebhookSignature } from '@kolaylogin/backend';

// Low-level
const result = verifyWebhookSignature({
  secret: process.env.KL_WEBHOOK_SECRET!,
  body: rawBody,                                 // raw request body as string
  signature: req.headers['x-kl-webhook-signature'] as string,
  timestamp: req.headers['x-kl-webhook-timestamp'] as string,
  toleranceSeconds: 300,
});
if (!result.valid) return res.status(401).json({ error: result.reason });

// Or the throwing variant
assertWebhookSignature({
  headers: req.headers,
  rawBody,
  secret: process.env.KL_WEBHOOK_SECRET!,
});

PaymentsClient

Thin wrapper around the instance API's payments surface — create intents, list payments, and issue refunds. Requires a server-to-server admin key (coming soon) or a session token for user-scoped calls.

import { PaymentsClient } from '@kolaylogin/backend';

const payments = new PaymentsClient({
  // baseUrl defaults to https://api.kolaylogin.com
  authToken: process.env.KL_SERVER_TOKEN!,
});

const intent = await payments.createPaymentIntent({
  amountCents: 2500,
  currency: 'usd',
  connectAccountId: 'acct_...',
});

SessionClaims reference

type SessionClaims = {
  sid: string;           // session id
  sub: string;           // user id
  env: string;           // environment (instance) id
  org?: string;          // active organization id
  org_role?: string;     // role inside the active org
  iat?: number;          // issued at (unix seconds)
  exp?: number;          // expires at (unix seconds)
  iss?: string;
  aud?: string | string[];
};

← Previous

@kolaylogin/react

Email & password