Skip to main content

Tenant Users and Directory

A tenant user is the link between an authenticated account on the platform and the tenant whose data and configuration that account is allowed to act on. Authentication establishes who a person is; the tenant user record establishes which tenant they belong to and what they look like inside that tenant's directory.

How users belong to tenants​

Authentication and tenancy are deliberately separated. An account is created once through the platform's authentication system, and a tenant user record is then created to attach that account to a specific tenant. The same authenticated account becomes a member of a tenant by gaining a tenant user record there.

The tenant user record acts as the membership marker for the tenant. It controls:

  • Whether the account can sign in to that tenant at all
  • The period during which the membership is valid
  • Whether the membership is currently active or has been deactivated
  • The tenant-specific defaults and preferences that follow the user around

Because tenancy is enforced everywhere, removing or deactivating a tenant user record cleanly revokes a person's ability to act inside that tenant without touching their underlying account.

Membership lifecycle​

Each tenant user record carries a validity period and an active flag:

AttributePurpose
Start dateWhen the membership becomes effective
End dateWhen the membership lapses, if known in advance
Active flagAllows the membership to be enabled or disabled without altering the dates
MetadataExtensible field for tenant-specific attributes that do not warrant a dedicated field

Together these allow an administrator to add a user ahead of time, schedule their departure on a known date, or temporarily disable access without losing the record. As with all Foundation entities, memberships are soft-deactivated rather than permanently deleted, so the historical record of who had access and when is preserved.

Default customer assignment​

A tenant user record can optionally point to a default customer. This is the customer record that the platform falls back to when an action implicitly requires a customer context and the user has not chosen one — for example, when a user signs in to a self-service portal that is scoped to a single customer.

Default customer assignment is:

  • Optional — most internal staff users have no default customer because they routinely work across many customers.
  • Tenant-scoped — the customer must belong to the same tenant as the user, so cross-tenant references are not possible.
  • Editable — administrators (and, where the platform allows it, users themselves) can change or clear the default at any time.

This is most useful for external users — typically end customers signing in to a portal — where it provides a convenient starting context without having to ask the user to pick a customer every time.

The tenant user directory​

The directory is the searchable list of members within a tenant. It surfaces just enough information for an administrator to find a user and act on them — for example, to add them to a permission group, assign a role, or pick them as a recipient on a record.

Each directory entry exposes:

  • The user's email address (resolved from the underlying authentication account)
  • Membership status (active, inactive) and validity period
  • The default customer assignment, if any
  • The tenant-specific metadata held against the membership

The directory is scoped to the current tenant — searching it never reveals users from other tenants. Visibility is also controlled: staff users with the appropriate permission can list and search every member of the tenant, while external users (such as portal users) can only see their own entry.

Relationship to permission groups and access control​

Tenant user records establish membership — they say "this account is a user of this tenant." They do not, by themselves, grant the user any specific capabilities. What a user can do inside a tenant is determined separately by the platform's access control layer:

  • Permission groups collect users into named groups that can be granted permissions collectively.
  • Direct permissions grant a specific user or group the ability to view, edit, administer, or own particular records or domains.
  • Role-based menus decide which navigation entries and actions a user sees.

The tenant user record is the anchor that all of these mechanisms hang off. Adding a user to a permission group, granting them a direct permission, or assigning them a role only makes sense for accounts that are first members of the tenant. Conversely, deactivating a tenant user record disables every grant that depends on it, because the user is no longer a recognised member of the tenant.