Public vs internal

Public vs internal API surface

Use this page to stay honest about what third-party integrations may call.

Public (integration-friendly)

Surface	Auth	Purpose
`GET /api/public/v1/customers`	Org API key Bearer	List customers
`GET /api/public/v1/appointments`	Org API key Bearer	List appointments
`GET /openapi.json`	None	OpenAPI document

The OpenAPI document is the contract.

Internal (not for third-party docs)

Do not build partner integrations on these without an explicit product contract:

Surface	Why it is internal
`/api/dashboard/`, most `/api/` session routes	Signed-in session cookie; used by the Cicini web app only
`/api/admin/*`	Platform administration only
`/api/stripe/*`, webhooks	Platform billing / Stripe
`/api/cron/*`	Scheduled platform jobs
HTML scraping of `/dashboard/**`	Unstable, not an API

Not shipped as public v1 (yet)

These product areas exist in the dashboard but have no public API endpoints in v1:

Services / service categories
Staff / team
Availability
Gift cards
Managing outbound webhooks through the API (configure them in the dashboard)
Create / update / delete of any resource via public API

If you need a resource that is not listed, contact us. Do not guess at paths.

Data isolation

Every public request is scoped by the organization on the API key.
Soft-deleted / inactive rows are excluded (isActive: true filters on customers and appointments).
PHI and sensitive fields: customer responses are an allowlist. Notes are never returned. Date of birth and gender require clients.sensitive:read. Do not log request or response bodies.

Outbound webhook signatures

Supported event webhooks are configured in the dashboard, not the public API. Each delivery includes:

X-Cicini-Signature: t=<unix seconds>,v1=<hex>
X-Cicini-Timestamp: event time as ISO-8601
X-Cicini-Event: event name
X-Cicini-Event-Id: id for this event, the same value on every retry

v1 is HMAC-SHA256 of t + "." + rawBody using the endpoint secret. Compare with a constant-time check, and reject timestamps more than 5 minutes off your clock. The secret is generated by Cicini and shown once when the endpoint is created.

const crypto = require('node:crypto');

function verifyCiciniWebhook(rawBody, signatureHeader, secret, nowMs = Date.now()) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/i.exec(signatureHeader || '');
  if (!match) return false;
  const timestamp = Number(match[1]);
  if (Math.abs(Math.floor(nowMs / 1000) - timestamp) > 300) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  const provided = Buffer.from(match[2], 'hex');
  const expectedBuf = Buffer.from(expected, 'hex');
  if (provided.length !== expectedBuf.length) return false;
  return crypto.timingSafeEqual(provided, expectedBuf);
}

Get started

Core resources

Examples