# `PhoenixKit.Users.Invitations`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.164/lib/phoenix_kit/users/invitations.ex#L1)

Context for organization invitation lifecycle management.

Handles creating, listing, accepting, declining, and cancelling invitations.

## Token Security

Follows the UserToken pattern:
- Raw token (32 bytes) is generated with `:crypto.strong_rand_bytes/1`
- SHA-256 hash is stored in the database
- URL-safe Base64 encoded raw token is sent via email or flash

## Flow

1. Admin calls `create_invitation/3` — invitation is created, encoded_token returned
2. For existing users: banner shown via `list_pending_for_email/1` + InvitationHook
3. For new users: invitation email with registration link containing encoded_token
4. User accepts via `accept_invitation_by_uuid/2` or declines via `decline_invitation_by_uuid/1`

# `accept_invitation_by_uuid`

Accepts an invitation by UUID in a single transaction.

Sets invitation status to `:accepted` and links the user to the organization.
Returns `{:ok, {invitation, user}}` on success.

## Errors

- `{:error, :not_found}` — invitation not found
- `{:error, :not_pending}` — invitation is not in :pending status
- `{:error, :expired}` — invitation has expired
- `{:error, reason}` — database or validation error

# `cancel_invitation`

Cancels a pending invitation by UUID (admin action).

Only `:pending` invitations can be cancelled.

# `create_invitation`

Creates an invitation for the given email to join the organization.

Returns `{:ok, invitation, encoded_token}` on success.
The `encoded_token` must be sent to the invitee (via email for new users,
or the UI banner handles lookup by invitation uuid for existing users).

## Validation

- Cannot invite a user already belonging to an organization
- Cannot create a duplicate pending invitation from the same org for the same email

# `decline_invitation_by_uuid`

Declines an invitation by UUID.

Only pending invitations can be declined.

# `get_by_token`

Looks up a pending, non-expired invitation by encoded token.
Used during registration to show org name and store the token.

Returns `{:ok, invitation}` or `{:error, :not_found | :invalid_token}`.

# `list_invitations`

Lists all invitations for an organization, ordered by most recent first.

# `list_pending_for_email`

Lists pending, non-expired invitations for a given email.
Preloads the `:organization` association for display in banners.

---

*Consult [api-reference.md](api-reference.md) for complete listing*