Confera | The Event OS

Overview

The Confera SDK is intentionally small: it signs requests with X-API-Key, parses JSON, and throws typed errors. In production, the reliability comes from how you integrate it.

This page gives you copy/paste defaults that work well for: kiosks, gates, websites, and vendors.

Key management

Keep keys server-only (Next.js Route Handlers / server functions / backend services).
Use one key per integration (website, kiosk, partner). This makes incidents easy to contain.
Grant the smallest scopes required (e.g. badges:write for kiosks).
Rotate keys regularly; if a device is lost, revoke only that device’s key.

Recommended env vars

bash

# URL of the Confera instance you are calling
CONFERA_BASE_URL="https://your-domain"

# Server-only secret
CONFERA_API_KEY="cat_..."

Timeouts

In production you should always set timeouts. The SDK supports timeoutMs.

Suggested baseline: 3–8 seconds for interactive flows (kiosk/gate), and 10–20 seconds for background jobs.

Create client with timeout + user agent

import { createConferaPublicClient } from "@confera/sdk";

export const confera = createConferaPublicClient({
  baseUrl: process.env.CONFERA_BASE_URL!,
  apiKey: process.env.CONFERA_API_KEY!,
  timeoutMs: 8000,
  userAgent: "my-app/1.0 (kiosk)",
});

Retries

Only retry transient failures. Good candidates are network errors and occasional503 responses. Avoid retrying most 4xx errors.

For check-in flows, treat 409 duplicate scans as success (idempotent UX).

Tiny retry wrapper (server-side)

import { isConferaApiError } from "@confera/sdk";

function sleep(ms: number) {
  return new Promise((r) => setTimeout(r, ms));
}

export async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (e) {
      lastErr = e;

      // Retry only the stuff that is usually transient.
      if (isConferaApiError(e) && e.status !== 503 && e.status !== 429) throw e;

      // Basic backoff
      await sleep(200 * (i + 1));
    }
  }
  throw lastErr;
}

Rate limits (429)

Kiosk/gate apps should debounce scans (ignore repeats for ~300–800ms).
If you get 429, slow down and retry with backoff.
Prefer one API key per device/team so one noisy device doesn’t affect others.

Caching & revalidation

Read-heavy endpoints (Website, Events, Exhibition) are great candidates for caching. In Next.js, consider fetching through a Route Handler and applying your own caching/revalidation policy.

Next.js Route Handler (cached response example)

import { NextResponse } from "next/server";
import { createConferaPublicClient } from "@confera/sdk";

export const revalidate = 60; // seconds

const confera = createConferaPublicClient({
  baseUrl: process.env.CONFERA_BASE_URL!,
  apiKey: process.env.CONFERA_API_KEY!,
  timeoutMs: 8000,
});

export async function GET() {
  const site = await confera.website.getSite();
  return NextResponse.json(site);
}

Logging

Log: endpoint, status code, and integration name (from your userAgent).
Do not log API keys or full request bodies containing sensitive info.
For kiosk/gate: log location and device identifier to trace operational issues.

Production checklist

Keys are server-only and scoped minimally.
Timeouts are set on the SDK client.
Retries only on transient errors (503/429 or network).
Kiosk/gate UX treats 409 duplicates as success.
Read-heavy endpoints have caching/revalidation.
Logging is safe (no secrets) and sufficient for ops.

SDK Production