Tenants

Tenants represent segments your users belong to. You might call these "accounts," "organizations," "workspaces," or similar. This is a common pattern in many SaaS applications: users have a single login joined to multiple tenants to represent their membership within each.

You use tenants in Knock to:

• Scope in-app feeds so users only see notifications relevant to their active workspace.
• Apply per-tenant branding in emails.
• Define per-tenant preference defaults that apply to all users within that tenant and per-user, per-tenant preferences.
• Apply per-tenant translations.
• Hold shared chat credentials and select tenant-scoped chat connections, so the same recipient can route to a different destination for each tenant.
• Include tenant IDs as an opt-in tag on Datadog and New Relic metrics.

Each tenant is uniquely identified by an id per-environment — in most cases the same ID you use in your own system. Tenants can store any number of custom properties alongside branding overrides and preference defaults, and are fully manageable via the API.

Behind the scenes, a tenant is a system-level Object in a special collection called $tenants, which means anything you can do with an object you can do with a tenant.

By default, Knock creates a stub tenant object for any tenant ID you pass when triggering a workflow. You can also use the tenant APIs to create and manage tenants explicitly.

Use the tenant API methods to create or update a tenant, including any custom properties and settings.

Property	Description
id	A string to uniquely identify the tenant

Property	Description
name	An optional name to associate with the tenant
*	Any custom properties you wish to store on the tenant
settings	A TenantSettings object to apply (see below)

Property	Description
branding.logo_url	A fully qualified URL for an image to use as the logo of this tenant
branding.icon_url	A fully qualified URL for an image to use as the icon of this tenant
branding.dark_logo_url	A fully qualified URL for the logo to use in dark mode. Defaults to logo_url if not set
branding.dark_icon_url	A fully qualified URL for the icon to use in dark mode. Defaults to icon_url if not set
branding.primary_color	A hex value for the primary color. Defaults to #000000
branding.primary_color_contrast	A hex value for the contrasting color to use with the primary color. Defaults to #FFFFFF
branding.dark_primary_color	A hex value for the primary color in dark mode. Defaults to #FFFFFF
branding.dark_primary_color_contrast	A hex value for the contrasting color in dark mode. Defaults to #000000
preference_set	A complete PreferenceSet to use as a default for all recipients with workflows triggered for this tenant

Tenants do not have a relationship to the users and objects you've identified in Knock — Knock does not know which tenant to associate with a given set of users. Instead, you must explicitly pass a tenant when triggering a workflow.

Tenants have a loose coupling to your users so Knock does not need to know anything about the roles and permissions model associated with your product. This means you have less data to synchronize to Knock and reduces the risk of drift between what's current in your system and what's reflected in Knock. If you need to model groups or lists of users, you can use our subscriptions model to do that.

Once a workflow run has been triggered with a tenant, the Knock workflow engine will:

• Find the tenant or create an empty tenant object if one does not exist.
• Expose the tenant object to the workflow run scope as a tenant variable.
• Tag all messages produced in the workflow run with the tenant id.
• Apply any branding overrides to templates rendered.
• Apply any preference defaults to the recipient's preference set.
• Fetch any recipient-specific tenant preference sets.
• Select chat connections tagged with the tenant ID, with untagged connections as a fallback.

Tagging messages by tenant makes it possible to query for tenant-specific messages in both the API and the dashboard, and to scope in-app feeds to a specific tenant.

A user or object can store several Slack, Microsoft Teams, or Discord connections and route each tenant's workflow runs to a different destination. Add knock_tenant_id to each connection and set it to the corresponding Knock tenant ID. Then pass that tenant ID when you trigger the workflow.

For example, a project object shared by Acme and Globex can store one Slack channel for each company. A workflow triggered with tenant: "acme" sends only to connections tagged with knock_tenant_id: "acme". If no connection matches, Knock falls back to untagged connections and never sends to a connection tagged for another tenant.

See scoping chat connections by tenant for setup examples, complete selection behavior, and how tenant-stored Slack and Microsoft Teams credentials work with scoped connections.

The full tenant object, including any custom properties, is available in your templates under the tenant namespace.

You can also use the tenant in step conditions to only trigger steps for particular tenants.

You can manage different sets of preferences for each user-tenant pair. A user may have different preferences configured for "Acme Fish Co." than they do for "Bell's Bagels," two workspaces within the same product. You can also set per-tenant defaults, where an admin in a tenant can set the default preferences for all users within that tenant. You can learn more in our per-tenant preferences documentation.