Members and invitations

An organization's members are the users with an accepted membership in it. People join by invitation, or an administrator can create an account for them directly. Joining grants almost nothing: what a member may do is decided by the roles they are given afterwards.

All of these routes act on the caller's active organization, taken from the session. None of them takes an organization id or uid, so a caller cannot act on an organization they are not in.

Who can do what, out of the box

The owner holds the user and superuser roles in their own organization. Someone who accepts an invitation gets no roles, only the per-person Org Member Baseline in the table's first three rows. You grant more by giving them a role; see Assigning roles. Nothing above reaches your app's structure (tables, handlers, endpoints, agents, jobs): that stays yours unless you grant it on purpose.

Inviting someone

# An administrator, signed in to the organization
curl -X POST "$AUTHORIC_URL/$APP_UID/autocrud/org_invitations/actions/org-invites" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "inviteeEmail": "sam@example.com", "expiresInDays": 14 }'

# The invitee, signed in to their own account
curl "$AUTHORIC_URL/$APP_UID/autocrud/org_invitations/actions/org-invites/received?status=pending" \
  -H "Authorization: Bearer $SAM_TOKEN"

curl -X POST "$AUTHORIC_URL/$APP_UID/autocrud/org_invitations/actions/org-invites/accept" \
  -H "Authorization: Bearer $SAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invitationUid": "<invitation uid>" }'

The invite answers with the invitation's uid and status:

{
  "invitationUid": "0199a6b4-7d21-7e05-8f3a-4b9c1d2e6f70",
  "status": "pending",
  "emailSent": true,
  "message": "Invitation sent to sam@example.com — they accept it in the app",
  "invitee": { "subjectType": "user", "email": "sam@example.com" }
}

An accepted invitation answers with orgUid, the organization joined. The session stays in its current organization: refresh with activeOrgUid to switch into the new one.

The rest of an invitation's life

Creating an account directly

For back-office tools and imports, an administrator can create the account and its membership in one call, without an email: POST /{appUid}/autocrud/org_invitations/actions/org-invites/internal-create with inviteeEmail and optionally fname, lname and password. If an account with that address already exists it is added to the organization instead. A newly created account gets its own home organization, like any other, and joins yours at once. The response names the account by invitee.uid and says whether it was created.

Listing, removing and leaving

Removing a member ends their authority there in the same step: their roles in that organization are deleted and their pending invitations to it are revoked. Re-admitting them later starts from nothing, never from whatever they held before.

Three removals are refused, so an organization can never be left without someone in charge:

• nobody can leave, or be removed from, their home organization;
• the organization's owner cannot be removed;
• the last member holding an administrator or owner role cannot be removed.

Errors to branch on

These come from the organization handlers and are returned in error.code.

A caller without the grant for an action gets a 403 whose message names the action that was refused (for example org_invitations:orgInvitesCreate).

What's next