Members, roles and registration

Your product's end users are its members. A member holds one or more memberships, each homed at a node of the product's organization tree (a path such as /org/customers) with role keys from your vocabulary. Roles are flat: a route admits a member holding any of the roles it lists, and a member never confers a role it does not hold. How the pieces fit together is How authorization works.

Declaring roles and registration

Roles and registration are declared once, in [authenticate] of config/routes.toml:

[authenticate]
roles = ["admin", "staff", "customer"]
registration = "open"
default_roles = ["customer"]
default_org_path = "/org/customers"
admin_org_path = "/org"

Each production activation creates admin_org_path, default_org_path, the [authenticate.workspaces] parent and every nodes entry when missing. A node you remove from the block is never deleted by a release. An entry's display_name is set on its node at each production release, so changing it renames the node; an entry without one leaves the node's name as it is.

The posture that counts is the one in the release active in production; the product's other environments share it.

aircloud generate authentication writes this block, the sign-in pages, their session function and the base profiles in config/profiles.toml (Profiles and grants):

aircloud generate authentication
aircloud generate authentication --registration open

The first admin

You run nothing to get the first admin. At the first production activation of a release that declares [authenticate] roles, the platform invites you, the account owner, as a separate end-user identity, at admin_org_path, holding every declared role and the tenant:org scope. This happens once. A role you add to the vocabulary later reaches the admin only through aircloud members update. A release with an [authenticate] block but no roles bootstraps nobody.

Memberships and their ids

A user is a person: one identity, one sign-in. A membership is one place of that person in your product: a home node, the roles held there, the scopes the membership may delegate, and its grants. One person may hold several memberships — a customer account and a company they work for, or staff at two client nodes — and their homes never sit one inside another.

Every aircloud members command that changes a member addresses the membership, by its id, which aircloud members list prints beside the user id. To find all of one person's memberships, ask by the user id:

aircloud members list
aircloud members memberships 2891…

A request acts through one membership. In your product's site, the end user picks it at /_air/memberships, without signing in again; a session holding several and none selected is sent there (session_membership_required for a request that is not a page). On the CLI you act through your own memberships with --membership <id>, needed only when you hold more than one.

Managing members

aircloud members list --path /staff
aircloud members invite ada@example.com --roles admin,editor --path /staff
aircloud members invite ada@example.com --path /acme --scopes tenant:org --profile admin --profile-node /
aircloud members update 0198a3c4-… --roles staff
aircloud members update 0198a3c4-… --path /staff/night --scopes ""
aircloud members remove 0198a3c4-…
aircloud members remove 0198a3c4-… --block --confirm 0198a3c4-…
aircloud members blocks
aircloud members unblock ada@example.com

• Invite. members invite places a new membership at a node at or below yours, with the roles you name, the scopes it may delegate (tenant:org lets it manage the members below its own node) and, with --profile, a non-expiring grant of that profile at its home. You confer only roles and scopes you hold.
• Update. members update changes only what you name: --roles, --scopes, or --path, which moves the membership's home. A move is refused while one of the membership's grants, or a group it belongs to, would fall outside the new home (grant_outside_home, group_outside_home): revoke it first. A member who signed up on their own gets more roles only through a new invite.
• Peers. A member at your own node is yours to manage only when your roles and scopes there include all of theirs, and never yourself.
• Remove and block. members remove asks you to type the membership id (or takes --confirm). --block also blocks the member's address from registering again; members blocks lists the blocks below your node, and only members unblock lifts one.

Grants, groups and denies

A grant confers a profile at a node, optionally until a time; a group shares its grants with every member it holds; a deny refuses roles or operations at and below a node, whatever any grant confers. They are covered in Profiles and grants:

aircloud members grant 0198a3c4-… --path /staff --profile editor --profile-node / --expires-at 2027-01-31T00:00:00Z
aircloud members grants 0198a3c4-…
aircloud groups add 0198a3c4-… --node /acme --name night-shift
aircloud denies create --path /acme --ops entity.delete --entity orders

Nodes

Your clients and their teams are nodes of the tree. You create, archive and delete them from the CLI; a function does the same through the tree operations it declares (The acting node and elevation), and a signed-in end user can create a company of their own when the product declares workspaces (Workspaces).

aircloud org nodes list
aircloud org nodes create /acme --name "Acme Ltda"
aircloud org nodes rename /acme --name "Acme Comércio Ltda"
aircloud org nodes archive /acme
aircloud org nodes unarchive /acme
aircloud org nodes delete /acme --confirm /acme

A node's path is its identity and never changes; its display name is what people see — the members page, the NAME column of org nodes list. A name has 1 to 100 characters and no line breaks or other control characters (surrounding blanks are trimmed; anything else is refused org_node_name_invalid). A workspace's node is named by the name its creator gave it (Workspaces); a node with no name shows its last path segment.

A node is always created strictly below yours. Archive suspends everything acting at or below the node — sessions, public routes, events, crons and direct invokes — until you unarchive it; nothing is deleted. Delete erases an archived node and everything at or below it, once the archive has settled, and cannot be undone.

Reviewing access

aircloud members review --window 720h
aircloud members review --node /acme --window 168h
aircloud authz who --node /acme

members review lists, for a node, the grants expiring within the window, the profiles no grant references, the groups with no member and who holds tenant:org. authz who lists who reaches a node, with their roles there, and authz explain says why one member may or may not act (How authorization works).

The members page

aircloud generate members adds an admin area to the site where your admins manage members themselves, protected by a route role (admin by default):

aircloud generate members
aircloud generate members --prefix /team --roles admin,staff

An admin invites a member at a node picked from a list: the admin's own node, selected by default, and the nodes below it that exist and are not archived — each shown by its display name with its path as a hint, Acme Ltda (/org/workspaces/acme), or by its last path segment when it has no name. The page never makes up a node, so create the nodes your members belong to first (aircloud org nodes create, or [authenticate] nodes, above). The same list is offered for a grant's node and a new group's node. The invite button is disabled while the invite is being sent, so a second click sends nothing.

Which records a member can read and write is decided per entity: see Owner and shared entities.