POST /api/v1/users/ with email/name/role (from the Users page,
or directly) creates the User with status: "pending" — not immediately active — and emails a single-use invite link, valid 7 days. role is required: the id of one of your
Organization's real Roles, chosen at invite time — never a free-text value, and never
another Organization's Role.
POST /api/v1/users/invite/accept/ with the
token from that email (optionally a password) flips the account to status: "active" and, in the same
transaction, creates a real, ACTIVE Membership with exactly the Role selected when the invite was sent — no separate
assignment step, and no silent default Role either. Their very first sign-in already
carries that Role's exact Permissions. A PENDING account cannot sign in through any
method before acceptance — User.is_active is
derived directly from status, so this is
enforced everywhere a User is resolved, not just at one entry point.
If the Role selected at invite time is deleted before the invite is accepted (invites are valid up to 7 days), acceptance fails the same way an expired or already-used token does — there is no fallback to a different Role.