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.

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.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
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

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.

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.

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 tenant preferences documentation.