# 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](authorization.md). ## Declaring roles and registration Roles and registration are declared once, in `[authenticate]` of `config/routes.toml`: ```toml [authenticate] roles = ["admin", "staff", "customer"] registration = "open" default_roles = ["customer"] default_org_path = "/org/customers" admin_org_path = "/org" ``` | key | what it says | |---|---| | `roles` | the product's role vocabulary; every other role a release names comes from it | | `admin_org_path` | the node of the product's first admin; required with `roles`, refused without | | `registration` | `invite` (the default): only you place end users, through `aircloud members invite`; `open`: anyone may sign up | | `default_roles` | the roles a self-registered end user receives (`open` only) | | `default_org_path` | where a self-registered end user is placed, strictly below `admin_org_path` (`open` only) | | `nodes` | further fixed nodes of the product, for example `nodes = ["/org/staff", { path = "/org/marcas", display_name = "Marcas" }]`: created with their ancestors beside the nodes above, each table entry with its display name; with them, the nodes your routes and triggers may name ([Every node you name is declared](acting-node.md#every-node-you-name-is-declared)) | 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](profiles-and-grants.md)): ```sh 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: ```sh 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 `, needed only when you hold more than one. ## Managing members ```sh 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](profiles-and-grants.md): ```sh 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](acting-node.md)), and a signed-in end user can create a company of their own when the product declares workspaces ([Workspaces](workspaces.md)). ```sh 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](workspaces.md)); 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 ```sh 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](authorization.md#asking-why)). ## 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): ```sh 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](entities.md). --- Rendered from aircloud 0.1.12 at commit d84a0ce6dae53629277f656d96d81549df36807e.