Skip to main content
Knock2’s multi-tenant system lets you provision isolated Knock2 workspaces — called tenants — for each of your customers or sub-products. Each tenant gets its own tracking script, API key, and visitor data, completely separate from every other tenant you manage. Whether you’re an agency running campaigns for dozens of clients or a SaaS platform embedding visitor identification into your own product, multi-tenant architecture gives you the programmatic control to spin up, configure, and deactivate workspaces at scale without manual intervention.

​
Who should use multi-tenant?

Agencies

Managing Knock2 on behalf of multiple clients. Provision a dedicated, isolated workspace for each client so their data never mingles.

SaaS Platforms

Embedding visitor identification directly into your own product. Each of your customers gets their own Knock2 workspace under the hood.

Resellers

Distributing Knock2 under your own brand. Use the API to create and manage workspaces without your clients ever interacting with Knock2 directly.

Multi-Product Developers

Building stacks that span multiple products or domains. Keep visitor data scoped to the right product with separate tenants per project.

​
Key concepts

Understanding three core concepts will help you design your multi-tenant integration correctly before you write a single line of code.

​
Parent tenant

Your parent tenant is the top-level Knock2 account. It acts as the provisioning authority — every child tenant you create is owned by and associated with your parent. You authenticate all tenant management operations using your master API key: creating, updating, deactivating, and reactivating tenants require the tenants:write scope; listing tenants and reading their allocations/usage require tenants:read.

​
Child tenant (product_slug)

Each child tenant is a fully self-contained Knock2 workspace. Once created, a child tenant operates independently: its tracking script is installed on the target domain, its API key authenticates its own data queries, and its visitor records are stored in isolation. Child tenants cannot access or affect one another’s data — except that a parent key can deliberately read one child’s data at a time via the X-Knock-Tenant header, and a parent-level webhook subscription automatically also receives events from every child (see the Webhooks guide).

​
product_slug

The product_slug is derived automatically, not assigned by you: Knock2 cleans the domain you provide and namespaces it under your own account’s slug. This guarantees a child’s slug can never collide with a future direct signup for that same domain under a different account, and makes provisioning idempotent per domain per parent — retrying POST /v1/tenants for the same domain always resolves to the same slug rather than creating a duplicate.
Because the slug is derived from domain, the way to keep it predictable is to keep the domain you pass predictable — there’s nothing else to configure.

​
Tenant isolation

Every child tenant you provision is completely isolated from every other tenant. The table below summarises what each child tenant owns exclusively.
The child tenant’s API key is shown once in the creation response. You must store it immediately in your own secure storage. Knock2 does not expose it again after the initial response.

​
Required scope

Tenant management endpoints (create, update, deactivate, reactivate, set limits) require your parent API key to carry the tenants:write scope. Tenant visibility endpoints (list, get, read limits, read usage) require tenants:read instead. If your key lacks the required scope, the API returns 403 Forbidden. Check your account settings to confirm the scope is enabled on your master key before proceeding.

​
Next steps

Managing Tenants

Step-by-step guide to creating, configuring, and deactivating sub-tenants via the API, including script installation.

API Reference: Create Tenant

Full request/response schema for the POST /v1/tenants endpoint.