Invitations and the first account

Adapt the application from Getting started so the first account claims the instance and subsequent accounts need an invitation. Your application owns the invitation table and decides who may issue links and what accepting one grants.

This guide uses username identifiers, matching the walkthrough. For finished code, see the invitation-only example.

1. The invitation schema

Create lib/my_app/accounts/invitation.ex:

defmodule MyApp.Accounts.Invitation do
  use Ecto.Schema

  alias Ithibati.Schema.Identifier
  alias Ithibati.Schema.Invitation

  use Invitation, identifier: :username, format: Identifier.username_format()

  schema "invitations" do
    ithibati_invitation()
    timestamps(type: :utc_datetime_usec)
  end

  def changeset(invitation, attrs, opts \\ []) do
    invitation_changeset(invitation, attrs, opts)
  end
end

The macro adds the identifier, token_hash, expires_at, accepted_at and a virtual token. The identifier field must match the account schema's identifier. Add your own fields for a role, team or other grant, together with their changeset handling and migration columns.

A new invitation lasts seven days by default. invitation_changeset/3 accepts days:; using it on an existing invitation can extend the expiry while preserving its token.

The changeset checks whether an account already has the identifier. The account table's unique index remains the final guarantee when registrations happen concurrently.

2. Configure and migrate

Add this to config/config.exs:

config :ithibati, invitation_schema: MyApp.Accounts.Invitation

Generate a migration:

$ mix ecto.gen.migration create_invitations

Use the following body in the generated file:

defmodule MyApp.Repo.Migrations.CreateInvitations do
  use Ecto.Migration

  def change do
    create table(:invitations) do
      Ithibati.Migration.invitation_columns(version: 1)
      timestamps(type: :utc_datetime_usec)
    end

    Ithibati.Migration.invitation_index(version: 1)
  end
end

The explicit index call matters when Ithibati's initial migration has already run, as it has in the walkthrough. It creates the token's unique index if absent and can coexist with an initial migration that also creates it.

$ mix ecto.migrate

invitation_columns/1 adds these columns:

The plaintext token is virtual and is not stored. For an existing table, supply the same columns and required index. Most applications can keep :string: both changesets trim and lowercase identifiers. If you deliberately use PostgreSQL citext, for example to handle writes outside the changesets, select it explicitly:

Ithibati.Migration.invitation_columns(version: 1, type: :citext)

Install the citext extension before this migration; the helper does not create it. The identifier remains a :string field in the Ecto schema. type: changes only the identifier column, not the token or timestamps.

The type must be resolvable by the migration's database connection. If the extension lives outside its search_path, qualify the type, for example type: :"extensions.citext", or configure the connection's search_path to include that schema.

Migration and doctor checks do not require identical account and invitation identifier types. Choose their comparison semantics deliberately. For an existing table, use a new application migration to alter its column; do not edit a migration that has already run.

3. Replace the registration handler

Replace lib/my_app_web/auth.ex with this handler. It retains authentication and recovery from the walkthrough and adds the two registration paths:

defmodule MyAppWeb.Auth do
  @behaviour Ithibati.Web.Handler

  import Phoenix.Controller, only: [json: 2]
  import Plug.Conn, only: [put_session: 3]

  alias Ecto.Multi
  alias Ithibati.Identity.Grant
  alias Ithibati.Identity.Instance
  alias Ithibati.Identity.Invitations
  alias Ithibati.Web.Gate
  alias MyApp.Accounts.User
  alias MyApp.Repo

  @impl true
  def registration_subject(_conn, params) do
    if Instance.needs_setup?(),
      do: first_account(params),
      else: invited(params["token"])
  end

  defp first_account(%{"username" => username}) do
    %User{}
    |> User.changeset(%{"username" => username})
    |> Ecto.Changeset.apply_action(:insert)
    |> case do
      {:ok, account} -> {:ok, account.username}
      {:error, _changeset} -> {:error, :invalid_username}
    end
  end

  defp first_account(_params), do: {:error, :username_required}

  defp invited(token) do
    case Invitations.fetch(token) do
      nil -> {:error, :invitation_unknown}
      invitation -> {:ok, invitation.username}
    end
  end

  @impl true
  def register(conn, key_attrs, username, params) do
    registration_multi(username, params["token"], key_attrs)
    |> Repo.transaction()
    |> case do
      {:ok, %{account: account, recovery_codes: codes}} ->
        {:ok,
         conn
         |> Gate.log_in(account)
         |> put_session(:recovery_codes, codes)
         |> json(%{redirect: "/recovery-codes"})}

      {:error, :account, %Ecto.Changeset{} = changeset, _changes} ->
        if Ithibati.Schema.User.identifier_taken?(changeset),
          do: {:error, :username_taken},
          else: {:error, :invalid_username}

      {:error, _step, reason, _changes} ->
        {:error, reason}
    end
  end

  @impl true
  def authenticate(conn, account),
    do: {:ok, conn |> Gate.log_in(account) |> json(%{redirect: "/inside"})}

  @impl true
  def recovered(conn, account, nil), do: authenticate(conn, account)

  def recovered(conn, account, fresh) do
    {:ok,
     conn
     |> Gate.log_in(account)
     |> put_session(:recovery_codes, fresh)
     |> json(%{redirect: "/recovery-codes"})}
  end

  defp registration_multi(username, token, key_attrs) do
    account = User.changeset(%User{}, %{"username" => username})

    if Instance.needs_setup?() do
      Multi.new()
      |> Multi.insert(:account, account)
      |> Instance.claim()
      |> Grant.with_key_and_codes(key_attrs)
    else
      case Invitations.fetch(token) do
        nil ->
          Multi.new() |> Multi.error(:invitation, :invalid_invitation)

        invitation ->
          Multi.new()
          |> Multi.insert(:account, account)
          |> Invitations.accept(invitation)
          |> Grant.with_key_and_codes(key_attrs)
      end
    end
  end

end

Instance.needs_setup?/0 selects the path for the request. Instance.claim/2 enforces the one-time claim inside the transaction, including when two people try concurrently. A losing claim returns {:error, :bootstrap, :already_claimed, changes} and rolls back the account.

Invitations.fetch/1 returns a pending, unexpired invitation or nil. The handler checks again at completion and handles nil before calling accept/3. An invitation can expire or be spent between the challenge and the response.

Invitations.accept/3 checks the invitation's state again when it writes. It also compares its identifier with the account inserted by the :account step. A mismatch returns :identifier_mismatch; an invitation that can no longer be accepted returns :invalid_invitation.

Build the account from the approved username argument. The final request's token may differ from the one used to obtain the challenge. Rebuilding the account from that token's invitation would bypass the binding to the identifier originally approved.

Missing, unknown, expired and spent tokens all receive :invitation_unknown at the challenge step in this example. Your page can show one message for them.

4. Add the invitation page

Add live "/invite/:token", InviteLive inside the public live_session in your router. Create lib/my_app_web/live/invite_live.ex:

defmodule MyAppWeb.InviteLive do
  use MyAppWeb, :live_view

  alias Ithibati.Identity.Invitations

  @impl true
  def mount(%{"token" => token}, _session, socket) do
    {:ok, assign(socket, token: token, invitation: Invitations.fetch(token), error: nil)}
  end

  @impl true
  def handle_event("accept", _params, socket),
    do: {:noreply, push_event(socket, "ithibati:register", %{token: socket.assigns.token})}

  def handle_event("ithibati:failed", %{"error" => error} = payload, socket),
    do: {:noreply, assign(socket, error: message(error, payload["exception"]))}

  def handle_event("ithibati:done", _payload, socket), do: {:noreply, socket}

  defp message("ceremony_failed", name) when is_binary(name),
    do: "Your browser refused: #{name}."

  defp message(error, _name), do: message(error)

  defp message("invitation_unknown"), do: "This invitation is unavailable or has expired."
  defp message("invalid_invitation"), do: "This invitation is no longer available."
  defp message("identifier_mismatch"), do: "This invitation does not match the registration."
  defp message("already_claimed"), do: "Somebody has already set this instance up."
  defp message("ceremony_cancelled"), do: "The passkey prompt was dismissed or timed out."
  defp message("already_enrolled"), do: "That passkey is already registered."
  defp message("no_challenge"), do: "That registration is no longer available. Start again."
  defp message(_other), do: "Registration could not finish. Please try again."

  @impl true
  def render(assigns) do
    ~H"""
    <Layouts.app flash={@flash}>
      <p :if={@invitation}>
        The account will be called <strong>{@invitation.username}</strong>.
      </p>

      <div :if={is_nil(@invitation)} class="alert alert-error">
        <span>This invitation has been used already, or it has expired.</span>
      </div>

      <div :if={@error} class="alert alert-error">{@error}</div>

      <.button :if={@invitation} phx-click="accept" variant="primary">
        Accept with a passkey
      </.button>

      <div
        id="passkey"
        phx-hook="Ithibati.Web.Hooks.PasskeyCeremony"
        data-registration-challenge-url={~p"/auth/registration/challenge"}
        data-registration-url={~p"/auth/registration"}
        data-authentication-challenge-url={~p"/auth/authentication/challenge"}
        data-authentication-url={~p"/auth/authentication"}
        data-recovery-url={~p"/auth/recovery"}
      >
      </div>
    </Layouts.app>
    """
  end
end

The page sends the token with ithibati:register; the hook forwards it to both registration endpoints. It displays the invitation's identifier without offering to change it.

The fallback above covers other failures. For a richer interface, share a message module between this page and sign-in and cover the library codes listed in Handling failures.

5. Update the sign-in page

The public page should offer registration only while the instance needs its first account. In MyAppWeb.SignInLive, alias Ithibati.Identity.Instance and replace mount/3 with:

@impl true
def mount(_params, _session, socket),
  do: {:ok, assign(socket, username: "", error: nil, setup: Instance.needs_setup?())}

Add :if={@setup} to the username registration form:

<form :if={@setup} phx-change="validate" phx-submit="register">

Keep the sign-in button, recovery form and hook outside that conditional form. Add these clauses before the existing catch-all message/1 clause:

defp message("already_claimed"), do: "Somebody has already set this instance up."
defp message("invitation_unknown"), do: "Registration now needs a valid invitation link."
defp message("invalid_invitation"), do: "This invitation is no longer available."
defp message("identifier_mismatch"), do: "This invitation does not match the registration."

The page's setup assign controls presentation. The transaction remains the authority when another person claims the instance while the page is open.

6. Issue and deliver a link

Create invitations from an application action restricted to accounts allowed to invite others. For a first development check, run this in iex -S mix after claiming the instance:

{:ok, invitation} =
  %MyApp.Accounts.Invitation{}
  |> MyApp.Accounts.Invitation.changeset(%{"username" => "second_person"}, days: 14)
  |> MyApp.Repo.insert()

MyAppWeb.Endpoint.url() <> "/invite/" <> invitation.token

The returned struct carries the plaintext token; a later database read does not recover it. Deliver the link to its intended recipient. Ithibati does not send mail.

An invitation is a bearer secret: whoever holds the link can accept it. In an application keyed by email, mailing the token to that address can form the application's address-verification flow, because acceptance binds the account to the invitation's identifier. The token alone does not establish how its current holder obtained the link.

7. Check the flow

Run mix ithibati.doctor, then try this on a fresh development instance:

1. Open / and create the first account.
2. Sign out. The public page should no longer offer open registration.
3. Create an invitation through the console or your authorized invitation action.
4. Open the link and register its account with a passkey.
5. Save the codes and confirm access to /inside.
6. Open the same link again. It should be unavailable.

The bootstrap claim survives deletion of the account that made it. Use a fresh development database for another first-claim walkthrough; deleting an account is not a setup reset.

Composing additional application steps

The account insertion comes before Instance.claim/2, Invitations.accept/3 or Grant.with_key_and_codes/3. Each reads the account from the :account step; pass account: :person if your insertion uses another name.

Put invitation acceptance, bootstrap claims and application steps that can refuse before the grant. A failed Ecto.Multi result can contain earlier step results, including plaintext recovery codes, so do not log the whole tuple.

For acceptance outside a WebAuthn ceremony, Invitations.account_attrs/1 supplies the invitation's identifier for account creation. In a ceremony, continue using the approved subject as the handler above does.

If your transaction also updates another singleton row, acquire it and the bootstrap row in a consistent order throughout the application and its fixtures to avoid deadlocks.

Housekeeping

Invitations.expired/0 returns expired, unaccepted invitations. Invitations.delete_expired/0 deletes them and returns the count. Ithibati schedules no cleanup job; expired links are refused whether or not the rows have been removed.