Introduction: How Cockpit and Cardinal work together

Two complementary pieces of iCure work together to power your application. Cockpit is the admin console where you set up and manage your backend. Cardinal is the platform your application talks to at runtime through the Cardinal SDK. You use Cockpit to provision and configure things; your application then uses the Cardinal SDK every day to read and write data.

Open Cockpit

Cockpit runs entirely in your browser — nothing to install. Open Cockpit → cockpit.icure.dev to register or sign in, then follow along in Register & Log In.

Bootstrap your app from a template

You don't have to start from a blank project. Cardinal ships ready-to-clone starters in several languages, so you can go from "account created" to "app talking to the backend" in minutes. There are two kinds:

• Template apps — self-contained examples that showcase the main Cardinal SDK features, great for learning the API. Available for TypeScript, Kotlin, and Python (all in one repo), and Dart (separate repo).
• Boilerplates — starter projects already wired up with authentication and the SDK, meant as the foundation for your own app:
  • React (web) — cardinal-sdk-react-js-template
  • React Native (Expo) — expo-medtech-boilerplate
  • Flutter / Dart — cardinal-sdk-flutter-boilerplate

See the Quickstart for step-by-step setup in each language. Whichever you pick, you'll plug in the values from your project's "Ready to go" step — see Initialize the Cardinal SDK.

Start in Cockpit: registration creates your Environment

Before anything else: when you register in Cockpit, you create an Environment. The Environment is bound to your email address, and you become its only administrator with "Environment Access" — full control over everything inside it. (You can later invite more administrators; additional ones can be scoped to a single project with "Project Access" instead.)

Everything you build lives inside that Environment, in a simple hierarchy:

Environment            ← created on registration, bound to your email (you = sole Environment-Access admin)
└── Project            ← one application/solution and its database
    └── Tenant         ← an isolated slice of a project (multi-tenant projects only)

• An Environment can contain many Projects.
• A Project is single-tenant by default; a multi-tenant project contains many Tenants, each an isolated set of data and users.

The two sides

Cockpit — the admin console

Cockpit is a web app for provisioning and configuring your iCure backend. It doesn't store your medical data itself — every action you take in Cockpit is performed through the Cardinal SDK against the iCure Cardinal backend. In Cockpit you:

• create Projects (and, for multi-tenant projects, Tenants);
• create the users your application will have (see the user types below) and the Administrators who manage the project;
• wire up External Services (email and SMS gateways, captcha);
• configure the Authentication Process (the email/SMS one-time code) — it's what lets your application's end users register themselves and log in (it references the project's group and parent organization). Creating users in Cockpit doesn't require a process; your app's self-registration and login flows do;
• manage Roles & Permissions, External JWT, Custom Properties, and read Metrics and storage usage.

Cardinal SDK — the client library

The Cardinal SDK (@icure/cardinal-sdk) is the library your application embeds (React, React Native, Python, …) to talk to the iCure backend. It gives you authenticated, end-to-end-encrypted access to the medical data model, organised as API namespaces — among them:

• People & access: User, HealthcareParty, Patient, Device, Role, Permission
• Clinical data: Contact, HealthElement, Document, Form, Message, Topic, Invoice, CalendarItem/Agenda, Code
• Cross-cutting: Group, Auth, Crypto, DataOwner, Recovery, MaintenanceTask

All data lives inside Groups — iCure's container primitive — and the SDK is group-aware: most operations have a variant scoped to a specific group. That group model is exactly what Cockpit's Environment → Project → Tenant hierarchy maps onto.

User types

A project's users come in several types, each created from its own place in Cockpit:

• HCP — a healthcare professional (a person).
• Organization — an organizational party (e.g. a clinic or company). It's just another user type with its own creation UI — not a mandatory parent of the other users.
• Patient
• Device
• Custom Entities — coming in the next version of Cockpit.

Each user is a data owner: the Cardinal SDK's crypto layer (Crypto, CryptoStrategies, RecoveryKey, Shamir key sharing) manages their end-to-end encryption keys, so data is encrypted on the client and only readable by the parties it's shared with.

How they cooperate

        ┌──────────────────────────────┐
        │            COCKPIT            │   (you, to set things up)
        │  Environment → Project →      │
        │  Tenant · Users · Auth        │
        │  process · External services  │
        └───────────────┬──────────────┘
                        │ provisions & configures (via the Cardinal SDK)
                        ▼
        ┌──────────────────────────────┐
        │     iCure Cardinal backend    │   (Groups hold your data, end-to-end encrypted)
        └───────────────▲──────────────┘
                        │ authenticated, encrypted reads/writes
        ┌───────────────┴──────────────┐
        │        YOUR APPLICATION       │   (every day, via the Cardinal SDK)
        │     @icure/cardinal-sdk       │
        └──────────────────────────────┘

The typical loop:

1. Set up the backend in Cockpit — register (creating your Environment), create a Project, add your users, and configure an Authentication Process. You can create users directly in Cockpit without a process; the Authentication Process is what lets your application's end users register themselves and log in.
2. Collect the SDK configuration values — the final "Ready to go" step of project creation hands you the identifiers your application needs (project/group id, external-services spec id, authentication process id, …).
3. Initialize the Cardinal SDK in your app with those values, and authenticate.
4. Read and write data through the SDK — scoped to your project (and tenant), end-to-end encrypted.

info

Cockpit and your application both talk to the same backend through the same SDK. Cockpit is the "control plane" (set-up and administration); your app is the "data plane" (everyday use).

The data model (Cockpit ↔ Cardinal)

Cockpit gives friendly names to the underlying iCure concepts:

In Cockpit	In the Cardinal SDK	What it is
Environment	a top-level Group	created when you register; bound to your email; you are its sole Environment-Access admin
Project	a Group	one application/solution and its database
Tenant	a Group within a project	an isolated slice of a multi-tenant project
Administrator	a User with admin rights	manages the project in Cockpit (Environment- or Project-scoped access)
HCP / Organization	HealthcareParty	a healthcare professional, or an organizational party
Patient	Patient	an end user / subject of care
Device	Device	a connected device
Authentication Process	an auth process (email/SMS OTP)	how the end users log in / register to your application

Where to go next

• Register & Log In — create your Cockpit account (and Environment) and sign in.
• Create Your First Project — walk the project-creation wizard.
• Initialize the Cardinal SDK — plug the "Ready to go" values into your app.
• Managing Users — add your first end users (HCPs, patients, devices).

Core concepts — the building blocks referenced above: Environment · Project · Tenant · Organization · HCP · Patient · Device · Administrators & Access Levels · Authentication Processes.

Cardinal SDK docs — for the developer side: SDK documentation · How to initialize the SDK · The Cardinal data model · End-to-end encryption.

Templates & boilerplates — clone a starter and go: Quickstart · TypeScript · Kotlin · Python · Dart · React · React Native · Flutter.