XONIKhub MarketplaceFor developersOpen the app

← For developers

Building an app

An app runs on your own server and shows inside the suite. Describe it in the app (Marketplace › Developers › Your apps), then publish it as a listing of the kind App. Each organization that installs it agrees to what it may do first.

The manifest

What you describe becomes the published manifest. Areas are parts of the API at read or write level; the app's key acts with the role of the person who installed it, so it never does more than they can.

{
  "name": "Order notes",
  "base_url": "https://app.example.com",
  "scopes": [
    "crm:read"
  ],
  "events": [
    "contact.created"
  ],
  "webhook_path": "/xonika/webhook",
  "screens": [
    {
      "key": "home",
      "title": "Overview",
      "path": "/screens/home"
    }
  ],
  "cards": [
    {
      "record_type": "contact",
      "title": "Notes",
      "path": "/cards/notes",
      "height": 240
    }
  ],
  "functions": [],
  "mcp_path": "/mcp"
}

What your server gets

Screens and record cards

Your pages open in a sealed frame. Their address carries xonika_context: a base64url JSON payload (org, user, app, record_type, record_id, exp five minutes ahead), a dot, and its HMAC-SHA256 (base64url) with the signing secret. Check it before showing anything.

Cards can sit on contact, company, deal, ticket, invoice and project pages.

An example server

// A whole app server in Node (no packages): node app.js
const http = require('node:http');
const crypto = require('node:crypto');
const orgs = new Map(); // organization id -> { api_base, api_key, signing_secret, webhook_secret } (keep these in your database)

function verifyCall(raw, header, secret) {
  const [t, v1] = String(header || '').split(',').map((p) => p.split('=')[1]);
  const want = crypto.createHmac('sha256', secret).update(t + '.' + raw).digest('hex');
  return v1 && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(want)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}
function readContext(token) {
  const [payload, sig] = String(token || '').split('.');
  const body = JSON.parse(Buffer.from(payload, 'base64url').toString());
  const org = orgs.get(body.org);
  const want = crypto.createHmac('sha256', org.signing_secret).update(payload).digest('base64url');
  if (!org || sig !== want || body.exp < Date.now() / 1000) throw new Error('not a real request');
  return { ...body, org };
}

http.createServer(async (req, res) => {
  const url = new URL(req.url, 'https://app.example.com');
  let raw = ''; for await (const c of req) raw += c;
  if (req.method === 'POST' && url.pathname === '/xonika/install') {
    const b = JSON.parse(raw);
    const known = orgs.get(b.organization_id);
    const secret = b.signing_secret || known?.signing_secret;
    if (!secret || !verifyCall(raw, req.headers['x-xonika-signature'], secret)) { res.writeHead(401); return res.end(); }
    if (b.event === 'paused') known.api_key = null; else orgs.set(b.organization_id, { ...known, ...b });
    res.writeHead(200); return res.end('{}');
  }
  if (req.method === 'POST' && url.pathname === '/xonika/uninstall') { orgs.delete(JSON.parse(raw).organization_id); res.writeHead(200); return res.end('{}'); }
  if (url.pathname === '/cards/notes') {
    // A card on a contact's page: read the contact with the organization's own key
    const ctx = readContext(url.searchParams.get('xonika_context'));
    const r = await fetch(ctx.org.api_base + '/crm/contacts/' + ctx.record_id, { headers: { Authorization: 'Bearer ' + ctx.org.api_key } });
    const c = await r.json();
    res.writeHead(200, { 'content-type': 'text/html' });
    return res.end('<p>Hello from the app. This is ' + String(c.first_name || '').replace(/</g, '&lt;') + '.</p>');
  }
  res.writeHead(404); res.end();
}).listen(8080);

Also