Skip to content

Organizations, teams & access

Every app instance is in exactly one organization: one its creator is in, or one made with it, as its package’s manifest says (Where an instance goes). An organization holds members with roles, nested teams (an app team per package it uses, with restricted child teams below for private channels) and the app instances, each with a list of grants that names who reaches it.

every app instance is in one organizationaccount (alice)passkeys · sessions · API keysCreateOrg with the first instanceorg "Notes" (alice's own)an ordinary org, one membernotes (grants: none)board (accounts: bob)POST /apps naming none: her only orgorganization "Acme" [namespace]members: owner · admin · member · guest · approvals · capabilities · invitesapp team: chat [group]metadata.app.package = chat#general (team: chat)child team (restricted)#private (team: child)CREATE_CHILD_TEAMapp team: kv-storekv (team: kv-store)team: design (open)a plain team, nested teams belowrows: lead · member · read-onlywiki (grants: org)site (grants: anyone)app instance [context] = one Raft group on its replicasmode: legacy (no app team) · standalone (all open) · shared (one closed)POST /apps/{app}/move takes an instance to another org; data stays put

Access has two layers. The node decides who reaches an app at all, from the app’s grants and the system state, on every request. Everything finer — who may edit which record — is the app’s own code, which can read the caller’s standing with env::org(), env::org_role(account) and env::in_team(account, team) (Who a run acts as).

Every rule on this page is enforced by the system group’s state machine when the command applies (The system group); the API checks most of them first so a refused request records nothing.

An app instance’s access is a list of grants (types::Grant, kept as types::Access), set at creation (POST /apps { grants }; absent: [org]) and replaced with POST /apps/{app}/access { grants } by its owner, an organization admin, or whoever manages its teams’ apps (MANAGE_APPLICATION on each team it admits, which a team’s leads hold, before and after the change); a list with no team needs MANAGE_APPLICATION organization-wide. Each grant is one way in, judged on its own, so an instance can be “team X plus two partners from outside”:

Grant Who it admits
org Every member of the app’s organization; a guest of the organization only while it has no app team. Not beside a team grant, which it covers
team { team } The team’s members (direct rows, and inheritance into an open team); at most 16 teams
account { account, scope? } One person. A member of the organization is a named member; anyone else is a guest, admitted only where the instance’s release and its organization allow guests. For an instance of a package with an app team in its organization, a named member must also be in that app team. scope is the app’s own (below); at most 1 000 accounts
anyone Any signed-in account, a member of the organization or not. Never a caller without an account (401): anonymous visitors come in only through public links

No grant is the owner alone. The owner reaches their app too, except that an instance whose only member grants are teams is reached by its owner only while they are in one of them (or named). A list with a grant twice, an unknown team or account, org beside a team, or a scope over 256 bytes is refused where it applies. Grants are written from cluster version 1.0.0-rc.33 (Feature::AccessGrants; 409 FEATURE_NOT_ACTIVE before). GET /apps/{app} answers them as grants.

Whatever changes an instance’s grants keeps the rest: giving an org instance an app team (ScopeApps) replaces its org grant with the app team’s, deleting a team takes the instances it alone admitted and the team’s grant from the others (or keeps them too, without its grant, with keepApps, below), and moving or handing an instance to another organization turns its team grant into the target’s app team or org.

The owner does not always reach their app. An organization’s app is reached only by the organization’s current members and its guests: its owner and the named members stop reaching it, and receiving its events, once they leave or are removed (the grants keep their names, so being added back to the organization restores it). An app on a team is reached by its owner only while they are in that team, as owner_in_org asks of the organization: an owner who leaves the team, is removed from it, or loses it when an open team is closed without them, stops reaching it (a person removed from Chat’s app team no longer reaches the channels they created), and has it back once they are in the team again. Likewise an instance only named people reach (a DM, a private channel) of a package that has an app team in its organization is reached only by those of its owner and named members who are in that app team (SystemState::app_team_of): someone removed from Chat’s team, who leaves it, or who loses it when it closes, is out of Chat’s DMs too, and has them back once in the team again. An instance of a package with no app team there keeps its names alone. A caller who does not reach it gets 404, so its existence is not disclosed; with no credential, 401. The check reads fresh system state, so removing someone from an organization or team holds on every node before their next request (Reads of the system state).

An organization’s app is managed by its owner only while they are a member of the organization (member or above, as owning an app there takes; SystemState::owner_acts). An owner who leaves, is removed or is made a guest keeps their name on the record but none of its powers: changing its access (so they cannot grant anyone to reach it again), its metadata, transferring or deleting it, upgrading it or making an upgrade key for it, uploading files to it or deleting its blobs. The organization’s admins (and its owner) still transfer it to a member or delete it, so an organization cleans up an app whose owner left; POST /apps/{app}/transfer is open to them too, with their own passkey. Likewise, an app on a team is managed by its owner only while they are in that team: out of it, they keep their name on it and none of the powers above, and the organization’s admins (or whoever manages the team’s apps) transfer it. The rules are judged where each command applies; SetAccess, SetAppMetadata, TransferApp, DeleteApp, UpgradeApp and CreateApiKey entries an earlier release logged replay as that release judged them (ownership alone, and no admin transfer, without owner_in_org; the owner without the team, without owner_in_team); the API marks new ones.

A member whose direct row in the app’s team is read-only still reaches the app, but only its views run for them: any other call is refused with 403 before it runs. A blob upload by them is refused before it starts.

POST /orgs { name, capabilities? } creates an organization with its creator as owner. capabilities (bits) sets what members can do unless set for them (defaultCapabilities), in the same CreateOrg entry, so an app need not follow with a second call (409 FEATURE_NOT_ACTIVE below cluster version 1.0.0-rc.29); absent, a new organization’s default stands. Its name is one line of 1 to 64 characters with no space at either end (400 otherwise). The owner or an admin renames it, with a passkey: POST /orgs/{org}/name { name } (412 CONFIRM_REQUIRED first; the consent is org:<org> / __rename_org / { name }, SystemCmd::RenameOrg), answered with { orgId, name }; a member below admin gets 403, and someone outside it 404. Nothing keeps a copy of the name, so GET /orgs/{org}, the orgs of /auth/me and an invite redeemed after the rename all answer the new one. A name is checked where the command applies: a CreateOrg an earlier release logged (without name_fits) replays taking any name, and an organization keeps the name it has until renamed.

Every app is in an organization. An organization is an organization: a person’s own is just one with a single member, its owner. From cluster version 1.0.0-rc.32 (Feature::OrdinaryOrgs) a sign-up makes none; an account’s organizations are those it creates (POST /orgs, or with an instance below) or is invited to.

A package’s developer says in its signed manifest which organization an instance goes into (instanceOrg, kept on the release’s record, PackageVersion::instance_org; meroctl app pack --instance-org or instance-org in [package.metadata.calimero]):

instanceOrg POST /apps naming org naming none newOrg: { name }
standalone 400 STANDALONE_INSTANCE a new organization, made with the instance a new one, so named
org that organization the creator’s only one; 400 ORG_REQUIRED with several, 409 NO_ORGANIZATION with none (create one, or accept an invite) 400 ORG_INSTANCE
either (default, and a raw bundle) that organization the creator’s only one; with none a new one; 400 ORG_REQUIRED with several a new one, so named

The creator’s organizations are those they are a member or more of. A new organization is an ordinary one owned by the creator, approving the release of the node it was made through and counted against maxOrgsPerAccount; it is named newOrg.name, else the instance’s name made to fit (one line, at most 64 characters), else the package’s id. It is written before the instance (two entries): a failure after it leaves the organization in place, as a unit’s member made before a failure stays. The people of a standalone instance are invited into its organization. An instance from a deployment follows its release’s mode the same way; a unit’s members always join their instance’s organization. A release recorded before the node kept the mode is read from its .mpk; installing it again records it.

Before 1.0.0-rc.32 (below that cluster version) a sign-up made the account’s personal organization in the same entry (CreateAccount { personalOrg }, named Personal) and an instance naming no organization went there. Such an organization keeps its personal: true flag (in GET /orgs/{org}, the orgs of /auth/me), and entries logged before the version replay as they applied. From the version on it is an organization like any other: no new one is made (CreateOrg { personal } is refused, 409 PERSONAL_ORGS_ENDED, and a sign-up’s seed is dropped), it counts against maxOrgsPerAccount (an account above the limit keeps its organizations; only creating one more is refused), an app there is transferred only to a member (as everywhere: 400 REJECTED), a deployment’s report names it, and a consent request with no scope ("scope": "account") stands for the account’s only organization. One thing stays: an instance there still reaches the accounts it names without making them members, whatever its package’s manifest says about guests.

Apps outside any organization were removed in a hard cutover (1.0.0-rc.20): data holding one is not read.

Members have one role each, ordered guest < member < admin < owner:

Role May
guest Once the organization has app teams, reach only the apps of the teams they have a direct row in (no org-access app, no open top-level team by inheritance); before that, its org-access apps as before. Always see only the people of their teams
member Also own apps in the organization and create top-level teams if they hold CREATE_TEAM
admin Manage members and their roles (below owner), capabilities, teams, organization metadata; delete the organization’s apps; approve releases, upgrade apps and approve outbound hosts (they hold every capability)
owner Everything, plus ownership and deleting the organization. Release approvals are also open to APPROVE_RELEASES holders, outbound approvals to MANAGE_APPLICATION holders (see Capabilities); app upgrades are the owner’s and admins’ alone

There is exactly one owner. SetOrgRole { role: owner } by the owner moves ownership and makes the previous owner an admin; the owner cannot be removed, only replaced. Leaving is removing oneself. Removing a member clears their capabilities, metadata and every team row they had. DELETE /orgs/{org} (owner, with a passkey step-up) deletes the organization with its teams, invites and apps, and unbinds the package signing keys it published (Publishers).

An organization also keeps metadata for its apps and frontends to read (admins, or members holding MANAGE_METADATA), per-member metadata (the member or an admin), the mero-tee releases its APPROVE_RELEASES holders approved, the outbound prefixes its MANAGE_APPLICATION holders approved, and its recent upgrade runs. An organization may also be a publisher: a package signing key is bound to it by the key’s own signature (APPROVE_RELEASES holders send the binding), and it then approves releases, and (where the package says so) runs upgrades, for every instance of that key’s packages (Publishers). Each metadata value is at most 16 KiB of JSON. Any member reads, with GET /orgs/{org}/apps, the apps they reach or manage there with the release each runs and its last upgrade (who, of which kind), the releases that govern each app, and the releases the cluster’s nodes run (Reading the approvals).

The owner and admins read what tells them a member may be locked out, with GET /orgs/{org}/members?detail=security (their own session on the cluster’s origin; never an API key or a package-bound session). For each member: the self-set name (memberMetadata.name), role, the teams they are in, passkeys (1, 2 or "3+": whether they have a backup, not how many devices they own), recoveryCode (set or not), lastActiveDay (the UTC day of their latest sign-in or session exchange; null when the node knows neither) and sessions (how many live sessions they hold).

Reader Sees Never
The account holder Everything about their own account: passkeys with labels and times, sessions, activity (/auth/me, /auth/sessions, /auth/activity) -
The organization’s owner and admins, about its members The fields above Credential ids, passkey labels (names people choose for their devices), sign counts and times, sessions, origins, activity, a recovery under way
A member below admin Nothing new (403) as above
A deployment’s managers, about customer organizations memberCount and activeMembers30d per organization (GET /deployments/{id}/orgs) Any account, name or per-member fact
The operator Nothing new: the Ops API has no read path into accounts Anything per account

A removed member leaves the listing at once, and someone outside the organization is answered as if it did not exist (404).

Teams (types::Team; meroctl’s groups) nest (parent), move (UpdateTeam { parent }, never under themselves), and are one of two kinds:

  • Open (join: everyone): whoever reaches the parent team — at the top, the organization — is a member too, unless they were denied JOIN_OPEN_TEAMS there. Membership flows down an unbroken chain of open teams.
  • Restricted (join: invite): only direct rows. A restricted team is a wall: nothing flows through it.

A direct row has a role (lead, member or read-only) and capabilities. A team’s creator leads it. Whoever leads a team, or an ancestor team, or is an organization admin, manages it: renames it, adds and removes members, creates teams under it, moves it within what they manage, and deletes it. A member who writes a team (a row that is not read-only, or inheritance into an open team) and holds CREATE_CHILD_TEAM there also creates a restricted team below it, and leads that one: this is how any member of an app’s team makes a private channel. An app team holds CREATE_CHILD_TEAM in its default capabilities, so it is on unless an admin turns it off; a CreateTeam entry an earlier release logged replays with only the parent’s managers creating below it (member_child_teams).

  • Removing someone from a team, or their leaving it, also removes their direct rows in every team below it, so a restricted child team (a private channel under an app’s team) does not keep them in. Closing an open team (POST /orgs/{org}/teams/{team} { join: invite }) does the same for whoever loses it then, being in it by inheritance alone: their rows below it go, and they are not barred, so opening it again lets them back into the team (not into the channels). An UpdateTeam an earlier release logged replays keeping those rows (close_drops_below).
  • A member who leaves a team, or whom a manager removes, does not come back by inheritance (Team::removed), so leaving an open team sticks. They return only when a manager adds them again or they redeem an invite that names the team; they cannot rejoin by themselves.
  • A member may join an open team they already reach as a plain member row, or leave any team themselves.
  • One account’s rows in several teams of the organization are set in one log entry with one passkey approval (POST /orgs/{org}/members/{account}/teams { teams: [{ team, role?, capabilities? }] }, SystemCmd::SetTeamMembers, consent __set_team_members { account, teams }): Calimero Home’s “give all apps” gives a member every app team at once. They are taken, or left, the same way (DELETE with { teams: [team] }, SystemCmd::RemoveTeamMembers, __remove_team_members { account, teams }). Each team is judged as its own team-member change would be, in order, and the entry applies all or nothing: one team the caller may not change refuses the whole batch. A batch names 1 to 64 teams (MAX_TEAM_BATCH), each once (400 BAD_TEAMS).
  • Deleting a team deletes the teams below it and the apps deployed to them: every instance whose only member grants are those teams’ (its team grants all go, and no org grant), even one that also names guests or other accounts. An instance another team or the organization admits only loses the deleted teams’ grants. When there are apps, it takes the deleter’s passkey: DELETE /orgs/{org}/teams/{team} answers 412 CONFIRM_REQUIRED with the apps and keepApps in its details, and the consent (__delete_team { team, apps }) names exactly those, so an app added since is not deleted on an old approval.
  • Keeping the apps (DELETE /orgs/{org}/teams/{team} { keepApps: true }, meroctl team delete --keep-apps, DeleteTeam { keep_apps }, Feature::KeepTeamApps, cluster version 1.0.0-rc.33, else 409 FEATURE_NOT_ACTIVE): those instances stay. Each loses the deleted teams’ grants and keeps its others (named members, guests, anyone, public links); one with no grant left has an empty grant list, which only its owner reaches (a team instance included). The consent states it (__delete_team { team, apps, keepApps: true }), and the answer lists them in keptApps (apps, the deleted ones, is empty). Without the flag, or absent in an entry an earlier release logged, they are deleted as before.
  • Reads are filtered: a team someone neither reaches nor manages is left out of GET /orgs/{org} and answers 404 on its own route.
  • A team keeps metadata the app defines (a folder’s name and colour), set by those holding MANAGE_METADATA for it.
  • A team may hold default capabilities (Team::default_capabilities): everyone in the team holds them there on top of their organization-wide ones, unless their row sets its own. Set with POST /orgs/{org}/capabilities { team, capabilities } (no account) by whoever manages the team or holds MANAGE_MEMBERS there, with a passkey (__set_default_capabilities { team, capabilities }). This is how “members may invite others to this app” is switched on per app.

An app deployed with access: team must be created by someone who writes that team (a member whose row is not read-only).

An app team is a top-level team whose metadata marks a package: metadata.app = { package, name } (Team::app_package). An organization has at most one per package: marking a second is refused. Only an owner or admin makes, changes or drops the mark: installing an app in an organization is theirs. The app’s instances use access: team on its app team, or on a restricted team below it (a private channel). The organization’s mode is derived from its app teams, never stored, and answered as mode on GET /orgs/{org} and GET /orgs/{org}/app-teams:

Mode When Means
legacy No app team Apps use org access, as before app teams. Behaves as standalone.
standalone Every app team open Everyone in the organization has every app; members may invite to the app (the team’s default INVITE_MEMBERS)
shared Some app team restricted Each app lists its people; invites name the app team; only leads and admins invite unless an admin turns on the team’s default

POST /orgs/{org}/app-teams { apps?: [{ package, name?, instances?, join?, keep?, childTeams? }], shared? } (an owner or admin, with a passkey: __scope_apps { apps, shared }, SystemCmd::ScopeApps) gives apps their own access lists in one log entry. For each package (absent: every package with an org-access instance in the organization) it finds or makes the app team (its creator leads a new one), gives a plain row to every member who reaches the instances now, and moves the instances (absent: every org-access instance of the package) to access: team on it. shared (absent: whether the organization then holds two app teams or more) closes every app team, everyone it held kept as a direct row, and takes INVITE_MEMBERS out of its default. Nobody loses an app. A new app team’s default holds CREATE_CHILD_TEAM in either mode (INVITE_MEMBERS too while standalone), so its members make private channels below it. App teams made before keep the default they had (nothing changes on replay or as a side effect) until an admin turns it on: a package’s childTeams: true adds CREATE_CHILD_TEAM to its app team’s default and to every row there that sets its own capabilities (a row added one by one keeps what it got then), and childTeams: false takes it out of both. With instances: [] the step moves no instance, and naming childTeams (as naming join) leaves shared, absent, meaning “no other team”, so POST /orgs/{org}/app-teams { apps: [{ package, instances: [], childTeams: true }, ...] } turns it on for every app team named, with one passkey, and changes nothing else.

To keep one app apart and leave the others as they are, a package names its own join in the same request: invite closes that app team alone, in the same log entry that fills its rows, and everyone opens it again (shared, absent, then changes no other team; shared: true with an everyone is refused). A close keeps, by default, everyone who reaches the app then, each as a direct row. With keep: [account, ...] (members of the organization only) the team’s leads and those accounts keep it, each with a row, and everyone else in it, by a row or by inheritance, loses it, together with their direct rows in the teams below the app team (its private channels), as a removal from the team takes them; they are not barred, so opening the team again lets them back in. Each package’s answer names its team’s join after the step and how many people it dropped. A single team also opens or closes with POST /orgs/{org}/teams/{team} { join } (MANAGE_VISIBILITY, an admin’s anywhere), which fills no rows: closing that way, only the existing direct rows stay, and whoever loses the team loses their rows in the teams below it too. GET /orgs/{org}/app-teams lists, to any member, each app team’s package, id, name, join, member count, default capabilities and whether the caller is in it or manages it (a guest: only their own).

In an organization that keeps its apps apart, a new app’s team holds only the people named when it is made. A member may instead hold a standing grant, every app added later (Org::all_apps, allApps on GET /orgs/{org}): each app team made from then on gives them a plain row, whoever else it names, so they reach every new app, open or closed. That is an app team made by ScopeApps (closed with a keep list too: they are kept), one a move makes in the organization (Moving an app), and a team an admin marks as an app team (unless they were removed from that team). It gives nothing in an app team already there: an admin adds them to those as anyone else.

The grant is the owner’s or an admin’s to give, with a passkey: on an invite, POST /orgs/{org}/invites { ..., allApps: true } (the consent’s arguments then name allApps: true; 403 below admin), which gives it to whoever redeems it, and later, POST /orgs/{org}/all-apps { account, allApps } (__set_all_apps { account, allApps }, SystemCmd::SetAllApps; false stops it, the rows already made stay). A member redeeming an allApps invite gets the grant, which spends a use. It ends with their membership: leaving, removal, or a recovery that removes them. ScopeApps, MoveApp and UpdateTeam carry all_apps_rows, which the API always sets; entries an earlier release logged replay making no such rows.

While an organization has app teams, creating the first instance of a package that has none there is an admin’s. In a shared organization a member sees, in GET /orgs/{org}, only the people of the teams they are in and its owner and admins; a guest sees only their teams’ people in every mode; owners and admins see everyone. Calimero Home, the portal that manages people, invites and apps across an organization, is one first-party package every cluster installs; it uses these routes and needs nothing else from the node.

POST /apps/{app}/move { toOrg, bringMembers? } (SystemCmd::MoveApp, with a passkey: <app> / __move { toOrg, bringMembers }) moves an app instance to another organization in one log entry. Its data stays where it is: the same group, replicas and state. Calimero Home’s “Merge organizations” moves every app of one organization into another this way.

  • Who: whoever manages the app where it is now (its owner while a member, or an admin there), as an admin or the owner of the target. Judged on the state of the moment, so a member removed from the source, or an admin of the target demoted, is refused.
  • Payer: its file bytes, compute runs and quotas go to the target. A move past the target’s file or compute quota is refused (429 QUOTA_EXCEEDED), as is one to a target that approves none of the releases holding the app now.
  • Grants: an org grant, or a team grant on its package’s app team, becomes a team grant on the target’s app team of the package. The target’s is used, or made when missing: open, unless every app team of the target is restricted (shared: true), where it is restricted like its others; an app team an admin closed alone leaves it open. The mover leads a new one, whose default capabilities are any new app team’s (CREATE_CHILD_TEAM, and INVITE_MEMBERS while open). A legacy target, and a raw upload (no package), get an org grant instead, so moving an app in never changes the target’s mode. Named people and anyone stay as they are, though only the target’s members (and its guests) reach it from then on; an instance only named people reach whose package has a closed app team in the target is reached there only through that team (see App access), so its owner and the people it brings get a row on it (below). An app on any other team (a restricted team below the app team, a plain team) is refused: that team’s leads, read-only rows and capabilities are grants of the source, which the target’s admins never saw. Give it an org or app-team grant first.
  • Owner: stays, and must be a member of the target once the move is done, or the move is refused: an organization’s app is owned by one of its members, and only a transfer the owner or an admin consents to changes who that is. An owner who reaches the app now gets a row on the target’s app team, as an owner reaches and manages an app on a team only while in it.
  • bringMembers: every member of the source who reaches the app joins the target at their role there, capped at member (a guest stays a guest; an admin comes in as a member, and the target’s admins grant more themselves), and gets a row on the target’s app team: the one an org or team instance moves to, or, for an instance only named people reach (a DM, a private channel), its package’s app team there when that team is closed, so they keep reaching it (an open one needs no row). Someone already in the target keeps their role. An app team made in the target gives its members who hold every app added later a row too. A MoveApp an earlier release logged (without accounts_in_app_team) replays giving its named people no such row.
  • Invites: the source’s invites naming the team the app leaves are revoked once no app of the source is on that team.

The answer is { appId, from, org, grants, created, added, revokedInvites }. A node from before this route answers 404, which clients take as “not supported here”.

Beyond their role, a member holds capability bits (types::caps, the MemberCapabilities values): organization-wide, with a default the organization sets, and per direct team row (a new row takes the member’s organization value). Admins and team leads hold them all where they manage.

Bit Name Checked by the node
1 << 0 CREATE_APP Creating an app in the organization (on its team, or org-wide)
1 << 1 INVITE_MEMBERS Minting an invite (org-wide, or on each team it names, where a team’s default capabilities count)
1 << 2 JOIN_OPEN_TEAMS Inheritance into open teams (granted by default)
1 << 3 MANAGE_MEMBERS Adding non-lead rows and setting capabilities in a team
1 << 4 MANAGE_APPLICATION Approving the organization’s outbound hosts (org-wide only). Upgrading its apps and its upgrade runs are its owner’s and admins’ alone from 1.0.0-rc.33 (App upgrades); before, this capability gave them too (on the app’s team, or org-wide)
1 << 5 CREATE_TEAM Creating a top-level team (or moving one to the top) without being an admin
1 << 6 DELETE_TEAM Deleting a team one does not manage
1 << 7 MANAGE_VISIBILITY Switching a team between open and restricted
1 << 8 MANAGE_METADATA Organization and team metadata
1 << 10 APPROVE_RELEASES Approving (or withdrawing) the mero-tee releases that hold the apps the organization governs: those of the packages it publishes, and its own apps of packages whose key is not bound; and binding a package signing key to the organization (org-wide only: a team grant does not reach it) (Release approvals)
1 << 11 CREATE_CHILD_TEAM Creating a restricted team below a team one writes, without managing it (the creator leads the new team); in an app team’s default

Bit 9 is unused: v1’s MemberCapabilities spends it on CAN_AUTHOR_ON_BEHALF, so a client that sends v1’s ALL grants nothing new by accident. A grant is POST /orgs/{org}/capabilities { account, capabilities } by an admin, with their passkey (as every membership change: roles, removals and leaving, team rows; 412 CONFIRM_REQUIRED first); GET /orgs/{org} lists who may approve releases (releaseApprovers).

An app’s own frontend cannot call these routes; it asks the node’s consent page to mint (createInvite) or accept (acceptInvite) an invite with the person’s passkey (The consent page).

POST /orgs/{org}/invites { role, teams?, ttlSecs?, uses?, allApps?, capabilities? } returns a token inv_…, after the inviter approves it with a passkey (412 CONFIRM_REQUIRED first; the consent binds { inviteKey, role, teams, expiresAt, uses }). Only the token’s Ed25519 public key is stored (inviteKey, the key whose seed is SHA-256("calimero.invite.v1\0" ‖ token)). An invite expires (7 days by default) and admits uses accounts (1 by default). Its role may not exceed the inviter’s and is never owner. Only the owner or an admin mints one with allApps (Every app added later). An inviter below admin needs INVITE_MEMBERS on each team the invite names (organization-wide when it names none), and may name only teams they see (a member of, or a manager): an organization-wide grant does not open a restricted team they are not in. capabilities (bits) is what a new member holds as their own setting (Org::capabilities) once they redeem it, in place of the organization’s default; a member already in keeps theirs. An inviter below admin may give only bits they hold organization-wide (403 CANNOT_GRANT_UNHELD, judged by the log too, so every node agrees; bits no capability has are 400 UNKNOWN_CAPABILITIES); the owner and admins hold every bit. The consent’s arguments then name capabilities, and the invite’s earlier shape (none) is unchanged (409 FEATURE_NOT_ACTIVE below cluster version 1.0.0-rc.29). POST /invites/{token}/redeem, by a signed-in person (no passkey prompt): the node signs the redemption with the token’s key, which every node checks where it applies, so a node that saw only the log cannot redeem an invite. It adds them at the invite’s role (or keeps a higher role they already have) and gives them a plain row in each named team. Only a redemption that does one of those spends a use: an account already in the organization at the invite’s role or above, and in every team it names (an owner opening their own link, say), gets the organization back and leaves the use for the person the invite was made for. The last use removes the invite; redeeming it after that, or after its organization is deleted, is refused 400 REJECTED (“this invite was used up, revoked or never existed”), and past its expiry “this invite has expired”. GET /orgs/{org}/invites lists the pending invites the caller may revoke (key, role, teams, uses left, expiry, creator and creation time; never a token): an admin all, a creator their own, a team’s manager those naming only teams they manage. DELETE /orgs/{org}/invites/{inviteKey} revokes one, with the same rule and a passkey (__revoke_invite { inviteKey }); an invite the caller may not see is 404. Invites made before record no creator. A redemption an earlier release logged replays as that release applied it (it spent a use whatever it changed): the API marks new ones (RedeemInvite { free_when_unchanged: true }). In the same way, a CreateInvite, RemoveTeamMember or DeleteTeam an earlier release logged replays without the rules above (the teams the inviter sees, the rows below, the passkey for apps); the API marks new ones (teams_seen, subtree, apps_need_consent).

A guest of an instance is an account invited to that one instance (and the apps its unit created for it) without joining its organization: an account grant naming someone who is not a member. From cluster version 1.0.0-rc.33 (Feature::Guests) a guest reaches the instance when both switches allow guests, the stricter winning:

Switch Where Default
The developer’s the release’s signed manifest, guests: "allowed" | "forbidden" (meroctl app pack --guests; kept on PackageVersion::guests: a release recorded before the node kept it, a raw bundle, takes none until the same .mpk is installed again) forbidden
The organization’s allowGuests, an admin policy set by its owner or an admin with a passkey: POST /orgs/{org}/settings { allowGuests } (org:<org> / __set_org_settings / settings, SystemCmd::SetOrgSettings); GET /orgs/{org} shows allowGuests: false when off allowed

A named account that is a member is a named member, with the member semantics above (its app team included). Access is judged fresh on every request, so taking a guest’s grant away (POST /apps/{app}/access, by whoever may change the instance’s access), turning the organization’s switch off, or an upgrade to a release that forbids guests holds from the guest’s next request. An instance in an organization made as a personal one before 1.0.0-rc.32 keeps its named accounts’ reach whatever the switches say (Personal organizations).

What a guest may do: what any account that reaches the instance may (call its methods and views, receive its events, read and upload its blobs, as a named member could), nothing more. They are not a member: they see none of the organization’s members, teams, other apps, invites, settings, usage or reports (404 as to a stranger), the app’s code sees no role for them (env::org_role is None), and they never manage the instance, approve its upgrades, set its secrets, list or export its sealed files (/files is the organization’s members’ and its owner’s), or delegate, link or move it. GET /apps/{app} shows a guest only their own grant. Unit members: a guest of an instance reaches the apps its unit created for it (AppRecord::links, transitively), judged by the instance’s grants and switches; an attached app is not part of it.

An instance’s managers (whoever may change its access) invite people with a link, like an organization invite but for one instance, on any instance: POST /apps/{app}/invites { ttlSecs?, uses?, scope? } returns a token inv_… once (412 CONFIRM_REQUIRED first; the consent is <app> / __create_app_invite / { inviteKey, expiresAt, uses, scope? }; only the token’s Ed25519 public key is logged, SystemCmd::CreateAppInvite, which needs Feature::AccessGrants too). It is made whatever the guest switches say now: whether a guest may come in is judged when someone redeems it. POST /invites/{token}/redeem (the same route as an organization invite; the node tells them apart) adds an account grant for the redeemer, with the invite’s scope (RedeemAppInvite, signed with the token’s key): a guest, or a named member when they are a member of the organization, never a new member. It answers { app, org, member }; one already named spends no use. A member of the organization (member or above) is always named; anyone else is admitted as a guest only while the instance’s release says guests: allowed and the organization’s allowGuests is on, judged on the state the redemption applies to, so a switch turned off after the invite was made holds (409 GUESTS_NOT_ALLOWED; the invite and its uses stay). GET /apps/{app}/invites lists the pending ones (key, uses left, expiry, creator, scope; never a token) and DELETE /apps/{app}/invites/{inviteKey} revokes one with a passkey (__revoke_app_invite { inviteKey }). Deleting the instance drops its invites. Bounds: MAX_APP_INVITES_PER_APP (64) pending per instance, MAX_APP_INVITES (10 000) in the cluster, MAX_APP_INVITE_USES (1 000) uses and MAX_APP_INVITE_TTL_SECS (90 days) each, MAX_ACCOUNT_GRANTS (1 000) names per instance and MAX_GRANT_SCOPE_BYTES (256) per scope. The consent page’s acceptInvite shows an instance invite as joining the app of a package in an organization, as a guest or, to a member, as the member they are.

The node decides only who reaches an instance. Anything finer, such as which channel of a chat a partner may read, is the app’s own rule, but the platform carries it for the app: an invite, and the account grant it makes, may carry a small opaque JSON scope the app defines ({"channel":"partners"}), which the node stores, shows to the instance’s managers and never reads. The app reads the caller’s scope with env::grant_scope() (WIT context.grant-scope, 0.5.6: the grant on the instance, or on the instance whose unit made it; none for anyone not named, and in a compute run). To let a partner into one channel of a chat, its managers invite them with that scope; the chat reads it and keeps them to that channel. A grant without a scope is the app’s whole. Changing the scope is changing the grant (POST /apps/{app}/access). A component built before 0.5.6 cannot read a scope, so it admits the person to all of it.

A public link lets anyone holding its token call one instance’s #[app::public] methods as an anonymous visitor, without an account and whatever the instance’s other grants (from cluster version 1.0.0-rc.32, Feature::PublicLinks). It is the third kind of grant beside member and named grants: a link grant in the instance’s list (Grant::Link: its key, label, expiry, rate, creator), which admits no account, only its visitors. It is made and revoked only on its own routes, each with a passkey; POST /apps/{app}/access keeps an instance’s links as they are, and refuses one it does not already hold. GET /apps/{app} shows link grants only to whoever may change the instance’s access. Whoever may change the instance’s access makes one with a passkey: POST /apps/{app}/public-links { label?, expiresAt?, ratePerMinute? } (412 CONFIRM_REQUIRED first; the consent is <app> / __create_public_link / { linkKey, label, expiresAt, ratePerMinute }) answers { link, token } once; only the token’s Ed25519 public key (link) is logged, so a node that saw the log cannot let anyone in. GET /apps/{app}/public-links lists them (never a token) and DELETE /apps/{app}/public-links/{link} revokes one with a passkey. A link lasts until revoked unless it names expiresAt; an instance holds at most 16 (MAX_PUBLIC_LINKS_PER_APP); deleting the instance drops them. The organization’s owner or an admin turns links off with POST /orgs/{org}/settings { allowPublicLinks: false }: no new link, and existing ones admit nobody at the visitor’s next call (allowPublicLinks in GET /orgs/{org}).

A visitor holds its own Ed25519 key (a browser keeps its seed in local storage) and sends, on every request, Authorization: Bearer vis1.<token>.<key>.<at>.<signature>: its public key (64 hex) and its signature over "calimero.visitor.v1\0" ‖ link ‖ 0 ‖ key ‖ 0 ‖ at, at within 5 minutes of the node’s clock (mero-js client.useVisitor({ link, seed }), the Rust client’s use_visitor). Nothing about a visitor is logged. The node admits it only to that instance’s calls and views of #[app::public] methods (403 for any other method, 403 VISITOR_ONLY on every other route, 404 for another app, 401 once the link is revoked, expired or turned off), at most ratePerMinute calls a minute per visitor on each node (429 TOO_MANY_VISITS; default 60, at most 600), besides a method’s own rate. The app sees Caller::Visitor { link, key } (WIT context.visitor, 0.5.6; a component built before sees Caller::Public), so it can tell visitors apart and count one answer per visitor; it has no org role, and the SDK’s guards refuse it.

An organization may hold a recovery key (Org::recovery): an Ed25519 key whose 32-byte seed its owner keeps offline; the organization stores only the public half (publicKey, base64url). It is set at creation (POST /orgs { name, recoveryKey }) or by the owner later, with a passkey (POST /orgs/{org}/recovery { publicKey }, consent org:<org> / __set_recovery_key / { publicKey }; null removes it). An organization created before recovery keys has none until its owner sets one.

An organization’s owner is an account, and an account acts only with its own passkeys. An owner who loses every passkey can no longer act for the organization, and nobody can act for them: an admin cannot change ownership, no Ops route touches an organization, and every decision carries its maker’s proof. Recovery moves the organization’s ownership to another account, the one the person signs up with a new passkey, after a delay during which the current owner can cancel. It acts on the organization only: one organization’s seed reaches nothing outside it (not the owner’s other organizations), and an account that owns several sets a key on each. To get the account itself back, see Account recovery.

recovery: start, 72 hours to cancel, finishbeforestart (at)readyAt = at + 72 hpending: cancel allowed, finish refused (409 RECOVERY_NOT_READY)finish allowedaccount/auth/recoverymake a codea passkey approvesbegin + startcode + new passkey; code spentcancelany passkey it still hasfinish: new passkeysessions + API keys endorganization/orgs/{org}/recoveryset a keyowner; seed offlinestartseed signs org+accountcancel / rotate keythe owner's passkeyfinish: new ownerold owners leave the orgtimes are the commands' own `at` (the proposing node's clock, replicated), never apply timeone pending recovery at a time (409 RECOVERY_PENDING) · every proof spent once (used_proofs)members see recovery.pending; the account's devices see recoveryPending in /auth/me
Step Route Who Proof logged Effect where it applies
Set or rotate POST /orgs/{org}/recovery { publicKey } (null removes; 412 first) The owner Passkey consent over org:<org> / __set_recovery_key / { publicKey } SetRecoveryKey: replaces the key and cancels a pending recovery
Set at creation POST /orgs { name, recoveryKey } The creator The session, as for any new organization The new organization holds the key
Start POST /orgs/{org}/recovery/start { nonce, signature } Any signed-in account (the new one) The seed’s signature over recovery_message(org, account, nonce) StartRecovery: pending = { account, startedAt, readyAt = startedAt + 72 h }
Cancel POST /orgs/{org}/recovery/cancel (412 first) The owner Passkey consent over __cancel_recovery / { account } CancelRecovery: nothing pending
Finish POST /orgs/{org}/recovery/finish (412 first) The pending account, at or after readyAt Passkey consent over __finish_recovery / { org } FinishRecovery: the account becomes the owner; every previous owner leaves the organization and its teams, and the apps they owned in it become the new owner’s

recovery_message is "calimero.org-recovery.v1\0" ‖ org ‖ 0 ‖ account ‖ 0 ‖ nonce (calimero_identity::recovery_message). The client derives the public key and signs on the person’s machine, and only the signature travels. It binds the account the organization goes to, so a node that saw the log cannot redirect it, and it is spent once (used_proofs). It is checked against the organization’s current key, at the API and again where the command applies, on every node, so rotating the key makes every signature under the old one fail.

Limits. RECOVERY_DELAY_SECS (72 hours) is judged at the commands’ own times (stamped by the node that takes the request, replicated with it), never at apply. One pending recovery per organization: a second start is 409 RECOVERY_PENDING until the owner cancels or the pending one finishes, so a seed holder cannot replace a pending recovery with their own. The nonce is at most MAX_RECOVERY_NONCE_BYTES (64); the key and signature text are bounded before decoding (MAX_RECOVERY_KEY_CHARS, 44; MAX_RECOVERY_SIGNATURE_CHARS, 88). A wrong seed is refused at the API before anything is logged, and no counter limits attempts: guessing a 256-bit seed is not a threat a counter changes. An unknown organization, one with no key and a wrong signature all answer 403 WRONG_RECOVERY_KEY, so an outsider learns nothing about which organizations exist or hold a key.

What members see. GET /orgs/{org} shows members recovery: { publicKey, setAt, pending } (absent when no key is set), so a client can warn every member, the owner first, while a recovery is pending. The recovering account is not a member yet; it reads the pending recovery’s times in the answers of start and finish. Nothing about recovery is in the Ops API or /ops/metrics.

Who Can they recover the organization? What limits it
The operator No The seed never reaches a node; no Ops route starts, cancels or finishes a recovery, and the operator’s signature is not a recovery proof
A node, or anyone reading the log No The log holds the public key and spent signatures, each bound to one account
An admin or member No Setting, rotating and cancelling need the owner’s passkey; starting needs the seed
An account outside the organization Only with the seed The seed is the credential
Someone who stole the seed Yes, unless the owner acts within 72 hours Every member sees the pending recovery; the owner cancels with a passkey and rotates the key
The owner, every passkey lost Yes Sign up with a new passkey, start with the seed, wait 72 hours, finish
The owner, passkeys and seed lost No Nobody can

A thief who already finished a recovery owns the organization; the delay and the warning to members are the defence. Recovery never changes an account’s passkeys: the previous owner’s account and its other organizations are as they were. Organizations written before recovery keys hold none (Org::recovery is left out when unset) until their owner sets one.

Recovering the data after every mero-kms replica is lost is a different mechanism: the recovery disk and its backup keys, below.

The recovery disk (merod --recovery-dir) writes, every 5 minutes, on every node that holds an app, the app’s state, the code it runs and its holder’s slice of the system state, each sealed to the holder’s X25519 public key (HPKE) and signed by the node’s attested receipt key (Recovery files). The backup holder is whoever upgrades the app (SystemState::backup_holder): the operator where it holds app upgrades, else the app’s organization, also for a package that declares upgrades: publisher. An account’s own apps are in an organization like any other app. No node ever holds a private half.

Holder Read Set
An organization GET /orgs/{org}/backup-key (any member) POST /orgs/{org}/backup-key { publicKey } by an org-wide MANAGE_APPLICATION holder, with a passkey (org:<org> / __set_backup_key / { publicKey }, 412 first)
The operator GET /ops/backup-key POST /ops/backup-key { publicKey }, signed with the operator key (operator / __set_backup_key / { publicKey }; The operator)

publicKey is 64 lowercase hex characters (400 BAD_BACKUP_KEY otherwise). The answer is { holder, key: { publicKey, setAt, setBy } | null, apps }, apps being how many apps’ backups open with it. Setting a key is the SetBackupKey command, gated by the backupKeys feature (1.0.0-rc.20, The cluster version); the owner-side routes answer 403 where the operator holds app upgrades. Until a key is set, nothing is written for that holder’s apps.

An organization’s apps come back on a cluster that does not hold them with POST /recover/holder: the holder’s own device opens the data keys of its files with its private key and sends them over the sealed channel, and the operator admits the import with its signature (SystemCmd::ImportHolder). The organization, its people (who sign in with the passkeys they had), its apps and its backup key come back; it is refused where any of them is on the cluster already (Recover after every key service is gone).