# Getting Started
This guide walks you through adding multi-account linking and switching to an existing Ash + AshAuthentication + Phoenix app. By the end, your users will be able to link multiple accounts to a single browser session and switch between them without re-authenticating.
## Prerequisites
AshMultiAccount adds multi-account support **on top of** an existing Ash + AshAuthentication + Phoenix app. Before installing, you need:
### Required
These are pulled in automatically as transitive dependencies of `ash_multi_account`:
- **Ash and Spark**
- **AshAuthentication** — you must have at least one authentication strategy configured
- **Phoenix** — controllers, plugs, and router all require it
You also need:
- **A user resource** — an Ash resource with AshAuthentication set up and registered in a domain (can be any module name, e.g. `MyApp.Accounts.User`, `MyApp.Accounts.Person`, etc.)
- **AshAuthentication Phoenix** (`ash_authentication_phoenix`) — provides `AshAuthentication.Phoenix.Controller` which is used by the auth controller that handles sign-in callbacks. Most Phoenix + AshAuthentication apps already have this.
> **Don't have a user resource yet?** Follow the [AshAuthentication Getting Started guide](https://hexdocs.pm/ash_authentication/get-started.html) to create one with an authentication strategy, then come back here.
### Also needed for LiveView
If your app uses LiveView for authenticated pages, also add:
- **Phoenix LiveView** (`phoenix_live_view`) — needed for the LiveView hook (`AshMultiAccount.Phoenix.LiveHook`) and the account switcher component (`AshMultiAccount.Phoenix.Components`).
> **Note:** `ash_authentication_phoenix` also provides `AshAuthentication.Phoenix.LiveSession` which the multi-account LiveView hook runs alongside. You likely already have it if your app uses AshAuthentication with LiveView.
The installer patches your existing resources and router; it does not create a User resource, domain, or authentication setup from scratch.
Specific version requirements are defined in the library's `mix.exs` — running `mix deps.get` will ensure compatible versions are resolved automatically.
### Data Layer
AshMultiAccount is **data layer agnostic**. It works with any Ash data layer — AshPostgres, AshSqlite, ETS, or others. The library generates standard Ash resources with attributes, relationships, and actions that work on any data layer. Both the demo app and the library's own test suite use ETS.
### Authentication Strategy
AshMultiAccount is **strategy-agnostic**. It works with any AshAuthentication strategy — password, OAuth2, magic links, API keys, or any combination. The library hooks into the session layer *after* authentication completes, so it doesn't care how the user originally signed in. The demo app uses password authentication for simplicity, but the same setup works with any strategy.
## Installation
Add the dependencies to your `mix.exs`. What you need depends on your setup:
<!-- tabs-open -->
### Using Igniter (recommended)
```elixir
# mix.exs
def deps do
[
{:ash_multi_account, "~> 0.1.0"},
{:igniter, "~> 0.6"},
# If not already present:
{:ash_authentication_phoenix, "~> 2.0"},
# Also add if using LiveView:
{:phoenix_live_view, "~> 1.0"}
]
end
```
### Manual
```elixir
# mix.exs
def deps do
[
{:ash_multi_account, "~> 0.1.0"},
# If not already present:
{:ash_authentication_phoenix, "~> 2.0"},
# Also add if using LiveView:
{:phoenix_live_view, "~> 1.0"}
]
end
```
<!-- tabs-close -->
Run `mix deps.get` to fetch the dependencies.
<!-- tabs-open -->
### Using Igniter (recommended)
The Igniter installer automates steps 1–6 below:
1. Adds the `AshMultiAccount` extension to your User resource
2. Creates the LinkedAccount resource (or patches it if it exists)
3. Registers LinkedAccount in your domain
4. Patches your auth controller's `success/4` to call `put_user_id/3`
5. Creates a `MultiAccountController`
6. Adds `use AshMultiAccount.Phoenix.Router`, the `Plug`, and routes to your router
Steps 7–8 (LiveView hook / controller plug and account switcher component) are app-specific — the installer prints post-install instructions for these.
```sh
mix igniter.install ash_multi_account
```
If `ash_multi_account` is a path or git dependency (not yet on Hex), run the installer directly instead:
```sh
mix ash_multi_account.install
```
You can also specify resource module names explicitly:
```sh
mix igniter.install ash_multi_account \
--user MyApp.Accounts.User \
--linked-account MyApp.Accounts.LinkedAccount
```
After running the installer:
- **LiveView apps:** Follow the post-install instructions for the LiveView hook (Step 7) and component (Step 8)
- **Controller-only apps:** Add the `LoadMultiAccount` plug (Step 7 alt) and component (Step 8)
If using a database-backed data layer (AshPostgres, AshSqlite), update the generated LinkedAccount resource's data layer configuration and run migrations:
```bash
mix ash.codegen create_linked_accounts
mix ash.migrate
```
### Manual
Follow all steps below to set up AshMultiAccount manually.
<!-- tabs-close -->
## Step 1: Add the Extension to Your User Resource
Add `AshMultiAccount` to your User resource's extensions and configure the `multi_account` section:
```elixir
defmodule MyApp.Accounts.User do
use Ash.Resource,
domain: MyApp.Accounts,
data_layer: ..., # any Ash data layer (AshPostgres, AshSqlite, ETS, etc.)
extensions: [AshAuthentication, AshMultiAccount]
multi_account do
linked_account_resource MyApp.Accounts.LinkedAccount
active_check {:status, :active}
display_fields [:name, :email, :avatar_url]
max_linked_accounts 5
end
# ... your existing attributes, actions, etc.
end
```
### Configuration Options
| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `linked_account_resource` | Yes | — | The LinkedAccount resource module |
| `active_check` | No | `nil` | `{field, value}` tuple — only active users can be linked/switched to |
| `display_fields` | No | `[]` | Fields loaded on users for the switcher UI |
| `max_linked_accounts` | No | `5` | Maximum linked accounts per session |
The extension's transformer will automatically add:
- A `:linked_accounts` calculation that resolves linked account records for a session
- A `:get_user_with_linked_accounts` read action used by the LiveView hook
## Step 2: Create the LinkedAccount Resource
Create a new resource with the `AshMultiAccount.LinkedAccount` extension:
```elixir
defmodule MyApp.Accounts.LinkedAccount do
use Ash.Resource,
domain: MyApp.Accounts,
data_layer: ..., # any Ash data layer (AshPostgres, AshSqlite, ETS, etc.)
extensions: [AshMultiAccount.LinkedAccount]
multi_account do
user_resource MyApp.Accounts.User
end
# If using a database-backed data layer, add its config here.
# For example, with AshPostgres:
# postgres do
# table "linked_accounts"
# repo MyApp.Repo
# end
end
```
The transformer generates the full schema automatically:
- **Attributes**: `session_token`, `status` (`:active`/`:inactive`), timestamps
- **Relationships**: `primary_user` and `linked_user` (both `belongs_to` your User)
- **Actions**: `create_linked_account`, `get_linked_accounts`, `activate`, `deactivate`, `read`, `destroy`
- **Calculations**: `is_active?`
- **Identity**: unique constraint on `{primary_user_id, linked_user_id, session_token}`
If using a database-backed data layer, generate and run the migration:
```bash
mix ash.codegen create_linked_accounts
mix ash.migrate
```
> **Note:** In-memory data layers like ETS require no migration step.
## Step 3: Register in Your Domain
Add the LinkedAccount resource to your domain:
```elixir
defmodule MyApp.Accounts do
use Ash.Domain
resources do
resource MyApp.Accounts.User
resource MyApp.Accounts.LinkedAccount
end
end
```
## Step 4: Update the Auth Controller
Your AshAuthentication auth controller needs to write the user ID to the session in a format the multi-account hook can read. Add a call to `AshMultiAccount.Phoenix.Session.put_user_id/3` in your success callback:
```elixir
defmodule MyAppWeb.AuthController do
use MyAppWeb, :controller
use AshAuthentication.Phoenix.Controller
def success(conn, _activity, user, _token) do
conn
|> store_in_session(user)
|> AshMultiAccount.Phoenix.Session.put_user_id(user.id)
|> assign(:current_user, user)
|> redirect(to: ~p"/")
end
def failure(conn, _activity, _reason) do
conn
|> put_flash(:error, "Incorrect email or password")
|> redirect(to: ~p"/sign-in")
end
def sign_out(conn, _params) do
conn
|> clear_session(:YOUR_OTP_APP)
|> redirect(to: ~p"/sign-in")
end
end
```
> **Note:** Replace `:YOUR_OTP_APP` in `clear_session/1` with your OTP application name (the `:app` value in your `mix.exs` project config).
> **Why is `put_user_id` needed?** AshAuthentication stores a JWT subject string in the session. The multi-account hook needs a plain user ID to resolve the current user after account switches. `put_user_id/3` writes the subject in a format both systems can read.
## Step 5: Create the Multi-Account Controller
```elixir
defmodule MyAppWeb.MultiAccountController do
use MyAppWeb, :controller
use AshMultiAccount.Phoenix.Controller,
user_resource: MyApp.Accounts.User
# Optionally override redirect paths:
# def after_link_path(_conn), do: ~p"/"
# def after_switch_path(_conn), do: ~p"/"
# def sign_in_path(_conn, primary_user_id), do: ~p"/sign-in?return_to=/link/p/#{primary_user_id}"
end
```
The controller mixin provides two actions:
- `link_account/2` — links a newly signed-in user to an existing primary account
- `switch_to_account/2` — switches the session to a different linked user
## Step 6: Add Routes
```elixir
defmodule MyAppWeb.Router do
use MyAppWeb, :router
use AshMultiAccount.Phoenix.Router
pipeline :browser do
# ... existing plugs ...
plug AshMultiAccount.Phoenix.Plug
end
scope "/", MyAppWeb do
pipe_through :browser
# Generates:
# GET /link/p/:primary_user_id -> MultiAccountController.link_account
# POST /link/p/:primary_user_id -> MultiAccountController.link_account
# GET /link/switch_to/:user_id -> MultiAccountController.switch_to_account
multi_account_routes MultiAccountController, MyApp.Accounts.User
end
end
```
`AshMultiAccount.Phoenix.Plug` ensures a session token UUID exists before any multi-account routes are hit.
## Step 7: LiveView Setup
> **Skip this step** if your app doesn't use LiveView. See [Step 7 alt](#step-7-alt-controller-only-setup) instead.
Add the multi-account hook to your authenticated live sessions. It should run **after** AshAuthentication's hook:
```elixir
live_session :authenticated,
on_mount: [
{AshAuthentication.Phoenix.LiveSession, :load_from_session},
{AshMultiAccount.Phoenix.LiveHook, {:load_multi_account, MyApp.Accounts.User}}
] do
live "/", HomeLive
# ... more live routes
end
```
The hook sets two assigns on every mount:
- `@current_user` — the user currently acting (may differ from primary after a switch)
- `@primary_user` — the primary account owner (`nil` when not in multi-account mode)
> **Tip:** If your app has both LiveView and controller-rendered pages, you can add the `LoadMultiAccount` plug (Step 7 alt) alongside the LiveView hook. They read the same session keys and coexist without conflict.
## Step 7 alt: Controller-Only Setup
> **Skip this step** if you already added the LiveView hook above and don't have controller-rendered pages that need multi-account assigns.
Add the `LoadMultiAccount` plug to your browser pipeline:
```elixir
pipeline :browser do
# ... existing plugs ...
plug AshMultiAccount.Phoenix.Plug
plug AshMultiAccount.Phoenix.LoadMultiAccount, user_resource: MyApp.Accounts.User
end
```
This plug sets the same `@current_user` and `@primary_user` assigns on `conn` that the LiveView hook sets on the socket. It must run after `:fetch_session` and `AshMultiAccount.Phoenix.Plug`.
For controller-only apps, this is the only integration step needed — the plug handles user resolution and multi-account switching for all controller-rendered pages.
## Step 8: Add the Account Switcher Component
Use the slot-based component in your layout or navigation:
```heex
<AshMultiAccount.Phoenix.Components.account_switcher
current_user={@current_user}
primary_user={@primary_user}
>
<:account :let={account}>
<.link :if={!account.current?} href={account.switch_url}>
{account.user.name}
</.link>
<span :if={account.current?}>{account.user.name} (current)</span>
</:account>
<:add_account :let={url}>
<.link href={url}>Add another account</.link>
</:add_account>
</AshMultiAccount.Phoenix.Components.account_switcher>
```
The component imposes no styling — you control all HTML and CSS through slots. It works identically in both LiveView templates and controller-rendered templates — it's a standard `Phoenix.Component` that only needs `@current_user` and `@primary_user` assigns.
## What's Next?
- [How It Works](../topics/how-it-works.md) — understand the data model, session tokens, and linking/switching flows
- [Phoenix Integration](../topics/phoenix-integration.md) — deep dive into each Phoenix module
- [Testing](../topics/testing.md) — set up test support and write tests for multi-account flows
