Skip to main content

Managing Tenants

A tenant is an isolated database inside a project โ€” its own users, processes, and configuration, kept separate from every other tenant in the same project.

How you manage tenants depends on the project's deployment model:

  • Multi-tenant project โ€” tenants are first-class, with their own Tenants page for creating, opening, and deleting them.
  • Single-tenant project โ€” there is exactly one tenant, kept hidden; it can't be deleted and is managed from the project's Configuration tabs.
Environment
โ””โ”€โ”€ Project โ† single- or multi-tenant
โ”œโ”€โ”€ Tenant โ† an isolated database
โ”œโ”€โ”€ Tenant
โ””โ”€โ”€ โ€ฆ
info

Switching a project between single- and multi-tenant is what reveals or hides the Tenants page โ€” see Switching the deployment model. See also Tenant and Project.

Managing tenants in a multi-tenant projectโ€‹

Open the project from its dashboard card (Manage project); for a multi-tenant project this lands on the Tenants page (/tenants/<id>), a two-pane layout โ€” the tenant list on the left, the selected tenant's details on the right.

The tenant listโ€‹

Each tenant is a card showing its name, storage (size of data and attachments), location (cluster), and a user breakdown โ€” Healthcare parties, Patients, Devices. The breakdown counts are clickable and open the tenant's Users tab pre-filtered to that type. The list infinite-scrolls in pages of 20, and a Search by name box (min. 3 characters) filters it. A project with no tenants shows an empty state with an Add tenant button.

Adding a tenantโ€‹

Add (or Add tenant on the empty state) opens the Create a tenant wizard โ€” a shorter cousin of the project-creation flow that provisions the tenant together with its parent organisation and registration processes, so a new tenant is usable right away. Its steps:

StepWhat you decide
TenantTenant name and Cluster โ€” the region hosting this tenant's database. The cluster defaults to the project's own; it can differ per tenant.
Usersthe same questions as the project wizard's Users step โ€” End users of the application (Patients, Healthcare professionals, Medical devices) and the data-sharing answers. The business model is not asked: it's the project's. See Create Your First Project.
Organisation (when needed)the Responsible organization that holds the sharing key โ€” asked when patients or devices are served, or when any sharing answer is Yes.
Ready to gothe Tenant group id, Tenant name, the parent organization's HCP ID and keys, and one process ID per channel and user type โ€” with Download all as *.json.

Skip and create an empty tenant on the Users step creates the database only โ€” no users, organisation or processes โ€” and jumps to Ready to go. You can add everything later from the tenant's Users and Processes tabs.

What the wizard provisions: a fresh database under the project (it inherits the project's Project ID โ€” your app reaches it with the same Application ID and is routed to the right database by the user's authentication); optionally the organisation with its private key (and recovery key if you enabled it); and a registration process per selected end-user type โ€” Patient and Practitioner Email or SMS Registration, named DEMO: โ€ฆ, one for email and one more for SMS if the Environment has an SMS gateway. Medical devices get no process. There is no External services step: the Environment's External Services decide which gateways are used, and if none is configured the email processes run on the demo SendGrid access (the Users step says so).

caution

Keys are shown only once. Finish asks "Have you downloaded the organisation's private key and saved the tenant data?" โ€” download the organisation's private key (and the JSON summary) before closing. See Recovery & Private Keys.

info

A partial failure never rolls back the tenant. If an organisation or process can't be provisioned, the summary reads "Tenant created with some issues" and lists each item under Items that could not be created; add the missing pieces from the tenant's Users and Processes tabs.

caution

Project Access creates empty tenants only. A Project-Access admin can't read the Environment's external services or process templates, so for them the wizard collapses to Tenant โ†’ Ready to go and the tenant is created without users, organisation or registration processes. Users can be added from the tenant's Users tab afterwards; registration processes must be set up by an Environment-Access admin. See Administrators & Access Levels.

info

Plan limit. On the Free plan a project can hold 5 tenants; once you hit the cap Add is disabled with a prompt to contact iCure to upgrade. See the Cardinal plan and Storage & Plans.

Opening and managing a tenantโ€‹

Selecting a tenant opens it in its own tabs, each scoped to that tenant alone:

TabWhat it's for
Overviewthe tenant's name, identifiers, user breakdown, business model (inherited from the project) and storage charts
Usersthe tenant's own HCPs, organizations, patients, and devices โ€” see Managing Users
Processesthe tenant's authentication processes (all process types available; read-only with Project Access) โ€” see Authentication Processes (setup)
Custom propertiesproperties scoped to this tenant โ€” see Custom Properties
External JWTthe tenant's external-JWT configuration โ€” see External JWT Configuration
Danger zoneUpdate indexes and Delete this tenant (below)

The Overview tab carries the editable Tenant Name, the Tenant group ID, the inherited Project ID (set up by you), the project's Business model (read-only here), the User breakdown โ€” whose badges open the tenant's Users tab filtered to that type โ€” and the Structured storage / File storage charts sized from the project's business model and this tenant's own user count (on the Free plan, a single Combined storage chart measured against this tenant's equal share of the project's fixed 500 MB quota โ€” remove unused tenants, or contact iCure for a personalised offer, to get more per tenant). The figures come from the metrics service and are refreshed every 24 hours; the tab says when they were last updated. (An Inspect tenant Group JSON button shows the raw Group object.) See Storage & Plans.

caution

When you initialize the Cardinal SDK, use the Project ID (set up by you) โ€” the same value across every tenant. There's no separate tenant ID in the SDK; the user's authentication routes them to the correct database. See Initialize the Cardinal SDK.

Deleting a tenantโ€‹

A tenant's Danger zone offers Delete this tenant, which permanently removes the tenant and its data.

danger

Deleting a tenant destroys all of its users and data and cannot be undone โ€” there is no way to recover a deleted tenant's database.

Managing the tenant in a single-tenant projectโ€‹

A single-tenant project holds exactly one tenant, kept hidden, so management is deliberately limited:

  • No Tenants page โ€” Manage project opens the project's Configuration page instead.
  • The tenant can't be deleted on its own; the project's Danger zone deletes the project and its single tenant together.
  • Users live on the project's Users page, not a per-tenant tab.

The hidden tenant's identifiers live on Configuration โ†’ Project overview (the Deployment section): its Tenant group ID (shown only for single-tenant projects) and the inherited Project ID (set up by you). See Project Overview & Configuration.

Project and tenant settings, one scope at a timeโ€‹

You can still configure the hidden tenant's Processes, Custom properties, and External JWT โ€” from the matching project Configuration tab. On a single-tenant project each of those tabs shows a Project scope / Tenant scope switch above the table; picking a scope swaps the table beneath it:

Configuration tabProject scopeTenant scope
ProcessesProject processesTenant processes
Custom propertiesCustom properties of the ProjectCustom properties of the Tenant
External JWTโ€ฆof the Projectโ€ฆof the Tenant

The tab opens in Project scope, unless the project has nothing on that tab and the tenant does โ€” then it opens in Tenant scope so you land on the items that exist. On a multi-tenant project there is no switch โ€” those tabs configure the project only, and each tenant is configured from its own Tenants โ†’ Manage tenant page.

info

A setting can sensibly live at either scope, and you can transfer or duplicate an entry between them. For processes, only Login and Generic email belong at the project level โ€” Registration goes on the tenant. See Authentication Processes (setup), Custom Properties, and External JWT Configuration.

Switching the deployment modelโ€‹

The single โ†” multi-tenant switch lives in the project's Danger zone (Configuration โ†’ Danger zone โ†’ Deployment model):

  • Switch to Multi-tenant โ€” reveals the Tenants page and lets the project hold more than one tenant. Right after the switch, if the project has no Login process yet, Cockpit offers to create one ("Your project is now multi-tenant"): the login process lets users of every tenant sign in through a single common URL. Create Login process opens the process form with the Email or SMS Login template preselected; Later closes the offer, and you can create it any time from Configuration โ†’ Processes. See Authentication Processes (setup).
  • Switch to Single-tenant โ€” only possible when the project has exactly one tenant; a project with multiple tenants can't be converted.
info

Unlike Transfer ownership and Delete on the same Danger zone tab, switching the deployment model is available to administrators with Project Access as well as Environment Access โ€” it's gated only by whether the project's current tenant count allows the switch, not by admin access level. See Administrators & Access Levels.

info

Older projects may have an unset or inconsistent deployment model. Cockpit treats those as multi-tenant by default and prompts you to set the correct model from the Danger zone; if a project is marked as both, pick the correct model (or contact iCure) to resolve it.

Where to go nextโ€‹

Cardinal SDK reference: tenants are Groups nested under the project group; each inherits the project's Application ID (projectId in SdkOptions).