Keys, schemas and media event hooks
The three surfaces most integrations touch: API key management, the Flow Builder JSON schema, and ESL media events from the call leg.
Where to start
API key management
Keys are issued per tenant and per environment, scoped to a role, and rotated without downtime by overlapping validity. Requests carry the key; tenant is resolved server-side and never taken from the payload.
Flow Builder JSON schema
Every published flow serialises to a versioned JSON document: nodes with typed configuration, edges with conditions, declared variables and the archetype and channel that constrain the node set.
ESL media event hooks
Subscribe to FreeSWITCH event socket streams for channel state, DTMF, recording boundaries and the recognition fork lifecycle, filtered to your tenant.
What the document contains
A flow document is the unit of deployment. It is diffable in review, versioned in your own repository if you prefer, and validated before publish against the archetype and channel constraints.
- nodes[]: id, type, config, timeout_ms, retry, on_error edge
- edges[]: from, to, condition expression over declared variables
- variables[]: name, type, scope, redaction policy for transcripts
- meta: archetype, channel, version, published_by, published_at
Signing and verifying
Outbound webhooks are signed with HMAC-SHA256 over the raw request body using the per-tenant secret, with the timestamp in the signature base to prevent replay. Verify before parsing, and reject anything older than five minutes.
Inbound API calls use a bearer key. A key that is valid but scoped to another tenant is refused and the attempt is logged against both tenants, because a cross-tenant call is a security event rather than a mistake.
Building against Ittisal?
We will provision a sandbox tenant with sample conversations and a test trunk.