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
POST /xonika/installwhen an organization installs it (and on updates, pausing and letting it run again):organization_id,api_base(https://hub.xonik.com/api/v1),api_key,scopes,webhook_secret,signing_secretandevent(installed, updated, paused, resumed). Answer 2xx or the install is undone.POST /xonika/uninstallwhen it is uninstalled: forget the organization.- Your webhook path: the events you chose, signed with
webhook_secret. - Calls are signed: header
x-xonika-signature: t=<seconds>,v1=<hex HMAC-SHA256 of "t.body" with the signing secret>.
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, '<') + '.</p>');
}
res.writeHead(404); res.end();
}).listen(8080);
Also
- Functions you pick are copied into each organization (their secrets are left for the organization to fill).
- An MCP path gives AI helpers your tools; a person approves every call.
- Paused: the key is withdrawn and the webhook stopped; a new key comes with "resumed".