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:

• Support a user having a separate notification feed per tenant
• Apply per-tenant branding in emails
• Define per-tenant preference defaults that apply to all users within that tenant
• Apply per-user, per-tenant preferences
• 🔜 Power per-tenant template overrides

A conceptual model of tenants

A tenant in Knock:

• Is uniquely identified by an id, per-environment. In most cases, this id is the same uuid used to identify the tenant in your system
• Can have any number of custom properties
• Can store branding overrides and preference defaults
• Can be managed via the API

By default, Knock will create a stub tenant object for all unique tenants that you trigger a workflow run for. You can also use the tenant APIs to create and manage tenant objects from your system to Knock.

Associating workflow runs with a tenant

It's important to note that tenants do not have a relationship to the users and objects you've identified in Knock. That means Knock does not know which tenant to associate with the set of users you're triggering a notification for. Instead, you must explicitly tell Knock as part of a workflow trigger to associate the workflow runs with a tenant.

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 do the following:

• Find the tenant or create an empty tenant object if one does not exist
• Expose that tenant object to the workflow run scope as a tenant variable
• Associates all messages produced in the workflow run with the tenant
• Applies any branding overrides to templates rendered
• Applies any preference defaults to the recipient's preference set
• Fetches any recipient-specific tenant preference sets

Using tenant data in a workflow run

The full tenant object will be exposed, including any custom properties, in the workflow run scope under the tenant namespace.

You can then use the tenant in a workflow to:

• Add per-tenant-specific template changes, like custom messages or details.
• Create per-tenant conditions to only trigger steps for particular tenants.

Syncing tenant data to Knock

To get tenant data into Knock, we expose various tenant-specific API methods. These methods make it possible to create or update a tenant, including any custom properties associated and any tenant settings, which include branding overrides and default preference sets.

Required attributes

Property	Description
id	A string to uniquely identify the tenant

Optional attributes

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)

TenantSettings

Property	Description
branding.primary_color	A hex value for the primary color
branding.primary_color_contrast	A hex value for the contrasting color to use with the primary color user
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
preference_set	A complete PreferenceSet to use as a default for all recipients with workflows triggered for this tenant

Messages and tenants

When a workflow is triggered with a tenant property, all of the Messages produced in the workflow run will be tagged with the id of the tenant.

Tagging messages by the tenant makes it possible to query for tenant-specific messages in both the API and the dashboard. We also expose this behavior for in-app feed messages, making it possible to expose per-user, per-tenant feeds (see below for an expanded guide on this usecase).

Working with tenants in the Knock dashboard

Tenant data is also exposed in the Knock dashboard. From the dashboard it's possible to:

• View information about specific tenants, including custom properties set
• View message logs of messages generated that were associated with the tenant
• View workflow run information for all runs associated with the tenant
• View and set custom branding settings
• View default preferences set for a tenant

You can find tenant information under the "Tenants" section in the left-hand menu of the dashboard.

Guides for using tenants

Scoping in-app feeds

Multi-tenancy is important in your notification system when handling in-app feeds. Lets look at an example. Imagine that we have a SaaS application, Collaborato, where our users belong to one or more different workspaces. When one of our users is active in a current workspace, we want to make sure they only see notifications that are relevant for that workspace. That is, a user in the "Acme Fish Co." workspace should only see notifications that are relevant to "Acme Fish Co."

Example

To support this use case within Knock, we can pass a tenant identifier into our trigger calls. This tenant does not have to be configured in any way beforehand, it can simply be a unique identifier you choose to represent this group.

When retrieving our feed to be displayed, we can then scope the feed to only show items relevant to the tenant:

By providing the tenant property here, we're letting Knock know that the notifications produced in the trigger call belong to a particular tenant and when we're showing the feed to our customers we only want to see the feed that's related to that tenant.

Under the hood Knock will ensure that the badge counts you receive for the feed will be relevant only to the active workspace, and that no real-time notifications will be received for any messages that aren't relevant to the user.

Custom branding

You can use tenants to define default branding settings when sending email notifications that override your account-level brand settings. When you trigger a workflow with a tenant, it will use any settings defined on that tenant in place of the account-level brand settings to style your email layout steps.

Example

Let’s say you’re a hospitality company and own two boutique hotels, “The Black Lodge” and “The Great Northern.” Both want custom branding for their reservation update emails.

First, we’ll want to add both of these hotels as Tenants. Navigate to the “Tenants” tab on the main sidebar of your dashboard and click “Create tenant." There, you’ll add a name and unique ID by which you'll reference the tenant when triggering notifications. You can also upload a logo, an icon, and select primary colors directly from the interface here.

Now that the tenant is set up, when you trigger a workflow with an email step you can pass the ID for one of these tenants. It will override the account branding settings with the settings you configured for your tenant. If you want to send a reservation reminder to the guests of The Black Lodge, you can pass the ID you set for that hotel, black-lodge, into the tenant field of the workflow trigger option to override default account settings with those you've created for this tenant.

Per-tenant user preferences and tenant preference defaults

Another advanced tenancy use case is managing different sets of preferences for each user-tenant pair. That is, a user may have different preferences configured for "Acme Fish Co." than they do for "Bell's Bagels," two hypothetical workspaces within our example collaboration app, Collaborato.

We also support the ability to set per-tenant defaults, where an admin in a tenant within your product can set the default preferences for all users within that tenant.

You can learn more about how to set per-tenant preferences and tenant preference defaults in our preferences guide.

Frequently asked questions