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
โโโ โฆ
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:
| Step | What you decide |
|---|---|
| Tenant | Tenant name and Cluster โ the region hosting this tenant's database. The cluster defaults to the project's own; it can differ per tenant. |
| Users | the 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 go | the 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).
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.
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.
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.
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:
| Tab | What it's for |
|---|---|
| Overview | the tenant's name, identifiers, user breakdown, business model (inherited from the project) and storage charts |
| Users | the tenant's own HCPs, organizations, patients, and devices โ see Managing Users |
| Processes | the tenant's authentication processes (all process types available; read-only with Project Access) โ see Authentication Processes (setup) |
| Custom properties | properties scoped to this tenant โ see Custom Properties |
| External JWT | the tenant's external-JWT configuration โ see External JWT Configuration |
| Danger zone | Update 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.
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.
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 tab | Project scope | Tenant scope |
|---|---|---|
| Processes | Project processes | Tenant processes |
| Custom properties | Custom properties of the Project | Custom 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.
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.
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.
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โ
- Tenant โ the concept: what a tenant is and how it maps to a Cardinal Group.
- Project Overview & Configuration โ the project-level settings and identifiers.
- Managing Users โ add HCPs, organizations, patients, and devices.
- Danger Zone โ the full set of destructive project/tenant actions.
- Initialize the Cardinal SDK โ how your app authenticates into the right tenant.
Cardinal SDK reference: tenants are
Groups nested under the project group; each inherits the project's Application ID (projectIdinSdkOptions).