Skip to main content

Platform API

The Platform API lets an external platform (built for EzyMigrate) provision and operate Knock Knock sub-accounts under an agency: create companies, list AI agents, subscribe to outbound webhooks, and log users in. It lives in backend: app/controllers/PlatformApiController.js (~1200 lines), routes in app/routes/platformApiRoutes.js. In-repo design doc: backend/docs/platform-webhooks-plan.md (partly stale — describes a Mongo poller and per-company webhooks; the shipped code is BullMQ + agency-scoped webhooks).

Three trust zones​

All three zones live in platformApiRoutes.js; the portal group uses an /agency/ prefix for webhook CRUD so it can't collide with the API-key routes.

1. Passport (portal) — super-admin / agency management:

RouteHandlerWho
PUT /platform-api/agencies/:id/accesssetAccess — flips agency.platform_api.enabled (does NOT mint a key)super-admin only
GET /platform-api/credentialsmasked key info (key_hint, timestamps, limits, sample payload)agency user + agency.manage_settings
PUT /platform-api/client-defaultssetClientDefaults — New client defaultsagency user + agency.manage_settings
POST /platform-api/rotate-keymints/rotates the API key — raw returned once, only the hash storedagency user
POST /platform-api/rotate-webhook-secretmints the HMAC signing secret (kk_whsec_…, encrypted at rest)agency user
GET /platform-api/webhook-config, GET /platform-api/webhook-deliveries, POST /platform-api/webhook-deliveries/:deliveryId/retrydelivery-log inspection + manual retryagency user
GET/POST /platform-api/agency/webhooks, PATCH/DELETE /platform-api/agency/webhooks/:webhookIdwebhook CRUD (portal variant)agency user

2. Public — POST /platform-api/login (platformLogin): looks the code up by hash (company.platform_login.secret_hash, select: false, sparse-indexed, lib/secretHash.lookupFilter; the raw code lives in the credential vault) and returns { user, token } for the company owner — same shape as goHighLevelLogin. createCompany returns the matching login_url (<portal_url>/platform-login/<secret>).

3. API key — middlewares/platformApiAuth.js sets request.agency:

RouteHandler
POST /platform-api/companiescreateCompany — email/name/credits/users, optional feature whitelist (unknown key = 400); capped by agency.initial_ai_credits + available_sub_accounts. Optional industry (service-business, real-estate, health-wellness, restaurant-hospitality, education, finance-insurance, digital-tech, custom), timezone (IANA, case normalised), agent_name (≤ 60 chars). Stamps company.created_via: 'platform_api' and copies the agency's default knowledge base
GET /platform-api/companieslistCompanies — agency-scoped, paginated (max 100), field-whitelisted
GET /platform-api/companies/:companyId/agentsgetCompanyAgents — inbound/outbound agents + the POST /ai-outbound/webhook trigger contract (incl. state, max 8 KB, echoed back in call.completed)
GET/POST /platform-api/webhooks, PATCH/DELETE /platform-api/webhooks/:webhookIdwebhook CRUD (API-key variant; same handlers via #authAgencyId)

New client defaults​

89bb8ea01, 5aff23622, 7214877e2; frontend faf5c2d3, 51551338. Card New client defaults on agency Settings → Platform APIs → Credentials (views/agency/settings/PlatformApis.vue): Industry, Assistant name, Time zone, Description (≥ 3 words, ≤ 200 chars), Working hours. Stored in agency.platform_api.client_defaults{industry, timezone, agent_name, description, working_hours[{day, start_time, end_time}]}. Precedence: create-request value → agency default; written to company.industry, company.timezone, company.working_hours, company.industry_details.{agent_name, default_description}. working_hours and description are defaults only, not create-call fields.

First login: company.created_via === 'platform_api' (the only value; absent on every other path) shrinks /setup to cs_start (password, plus name when first_name wasn't sent) and an invisible auto-saved cs_business — description written by AI from the default-KB PDFs (waits up to ~1 min), else the default description; hours default Mon–Fri 9am–4pm. See Onboarding. The in-app docs (components/agency/platform-api/PlatformApiDocs.vue, API Documentation tab) have a matching "First login" section; their agent_name text and the card placeholder still hardcode "Nox".

API-key auth (platformApiAuth)​

x-api-key (fallback api-key) → sha-256 hash → lookup agency.platform_api.key_hash with enabled: true, deleted_at: null. Keys are kk_live_ + 32 random bytes hex (helpers/PlatformApiHelper.js); only the hash is stored (select: false), key_last_used_at stamped best-effort. The key can only act on its own agency — the tenant boundary is the agency row the hash resolves to.

Outbound webhooks​

Two event types (PlatformWebhookModel.SUPPORTED_EVENTS): lead.captured and call.completed. Triggers are centralized:

  • lead.captured — fired in exactly one place, PersonResolverService.resolve(), whenever a validated email/phone lands (any source). CrmSyncHelper (and the chat/session controllers) carry explicit "do not fire here" notes — CRM sync deliberately does not emit platform webhooks. Idempotency suffix: user_session_id | sha1(name|email|phone)[:12].
  • call.completed — fired only by the cron PlatformCallCompletedWatcherJob (1 min): sweeps outbound inbound_outbound_calls ended 2 min–6 h ago without platform_delivery_processed_at, joins outbound_call_states by call_sid, enqueues, then stamps the guard field (not stamped if enqueue throws). Payload includes outcome classification (call_outcome / per-agent post_call_tags), transcript, recording URL, and the caller-supplied state.

Delivery pipeline​

  • helpers/PlatformWebhookHelper.js — envelope {id, type, api_version: '2026-06-01', created_at, agency_id, company_id, data} serialized once; HMAC sha256(secret, "<ts>.<rawBody>") in X-KnockKnock-Signature: t=<ts>,v1=<hex> plus X-KnockKnock-Event / X-KnockKnock-Delivery (job id = idempotency key) / X-KnockKnock-Timestamp. SSRF-safe: URL validated at write time (https in prod, no localhost/private/.internal), DNS re-checked at delivery, and custom http/https agents pin every resolved address (defeats DNS rebinding). 10 s timeout, no redirects, 1 MB response cap.
  • services/PlatformWebhookQueueService.js — BullMQ queue platform-webhooks (global.platformWebhooks, visible in Bull Board at /admin/queues): 8 attempts, full-jitter exponential backoff (60 s base, 6 h cap), concurrency 5. 4xx (except 408/429) = permanent failure; a webhook auto-disables after 5 consecutive dead deliveries.
  • Models: PlatformWebhookModel (platform_webhooks — agency-scoped, events, endpoint auth encrypted select: false), PlatformWebhookDeliveryLogModel (platform_webhook_delivery_logs, 30-day TTL, no secrets stored), OutboundCallStateModel (outbound_call_states — caller state by call_sid, 7-day TTL, upserted by AiOutboundCallController.webhook).

Secrets at rest — SecretCrypto​

helpers/SecretCrypto.js (AES-256-GCM, key from SECRET_ENCRYPTION_KEY, versioned blobs {v, iv, tag, ct}) encrypts secrets that must be replayed: the agency signing secret and webhook endpoint-auth credentials. The platform login code is no longer stored on the company: only secret_hash (lookup) stays there and the raw value lives in the credential vault. The Lead API key and the agency API key are hashed only, never decryptable. Don't reuse the legacy CryptHelper (non-AEAD, hardcoded key).

Lead API (company-scoped)​

A separate, simpler key surface on userSessionRoutes.js behind middlewares/leadApiAuth.js — the company is resolved from the key (by hash: company.lead_api.secret_hash); no company id is ever accepted from the caller.

The key is stored only as lead_api.secret_hash + secret_hint (… + last 4, lib/secretHash.keyFields) — CompanyController returns the raw key once at generation (owner only) and it can't be shown again; regenerating replaces it.

RouteHandler
GET /api/v1/lead/visitorsgetLeads — paginated (max 500), since/type/sort, bots + playground excluded
GET /api/v1/visitors/countvisitorsCount — day boundaries in the company's timezone. Now key-required — breaking (was public with inline key lookup before commit 7b0bc12cf)
GET /api/v1/lead/:user_session_id/transcriptleadTranscript — merged AI-voice + chat + phone transcript; foreign id = 404, not-ready = 200 { ready: false }

Which API-key middleware is which​

leadApiAuthplatformApiAuthapiKeyAuth
Headerx-api-key / api-keyx-api-key / api-keyx-api-key / api-key
Credentialcompany.lead_api.secret_hashagency.platform_api.key_hash (sha-256) + enabledenv BACKEND_API_KEY (alias WEBHOOK_API_KEY)
Context setrequest.company (_id, timezone)request.agencynone
Tenant scopeone companyone agencyglobal (internal service-to-service)
Used byLead API routesPlatform API key zoneinternal routes (internalKnoxRoutes, migrationRoutes, callEventsRoutes, …)