# `AshMultiAccount.Phoenix.Session`
[🔗](https://github.com/chriscox/ash_multi_account/blob/v0.1.1/lib/ash_multi_account/phoenix/session.ex#L1)

Session read/write helpers for multi-account functionality.

Provides functions that work with both `Plug.Conn` (controllers) and
raw session maps (LiveView hooks) for reading session values, and
`Plug.Conn` only for writing.

## Session Keys

- `"user"` — AshAuthentication subject string, format `"<short_name>?id=<UUID>"`.
  Both read (on mount/hook) and written (during account switches via `put_user_id/3`).
  Writing to this key is how account switching works at the session level.
- `"primary_user_id"` — UUID of the primary account owner
- `"session_token"` — UUID tying linked accounts to a browser session

# `conn_or_session`

```elixir
@type conn_or_session() :: Plug.Conn.t() | %{optional(String.t()) =&gt; term()}
```

# `clear_multi_account_session`

```elixir
@spec clear_multi_account_session(Plug.Conn.t()) :: Plug.Conn.t()
```

Clears multi-account session keys (`"primary_user_id"` and `"session_token"`).

Does **not** clear the `"user"` key.

Only works with `Plug.Conn`.

# `get_primary_user_id`

```elixir
@spec get_primary_user_id(conn_or_session()) :: String.t() | nil
```

Reads the `"primary_user_id"` from the session.

Accepts either a `Plug.Conn` or a raw session map.

# `get_session_token`

```elixir
@spec get_session_token(conn_or_session()) :: String.t() | nil
```

Reads the `"session_token"` from the session.

Accepts either a `Plug.Conn` or a raw session map.

# `get_user_id`

```elixir
@spec get_user_id(conn_or_session()) :: String.t() | nil
```

Parses the user ID from the session `"user"` key.

The session stores the user subject as `"<short_name>?id=<UUID>"` (matching
AshAuthentication's subject format). This extracts just the UUID.

Accepts either a `Plug.Conn` or a raw session map.

Returns the UUID string or `nil`.

# `multi_account_session?`

```elixir
@spec multi_account_session?(conn_or_session()) :: boolean()
```

Returns `true` if the session has both `"primary_user_id"` and `"session_token"` set.

Accepts either a `Plug.Conn` or a raw session map.

# `put_multi_account_session`

```elixir
@spec put_multi_account_session(Plug.Conn.t(), String.t(), String.t()) ::
  Plug.Conn.t()
```

Sets both `"primary_user_id"` and `"session_token"` atomically.

These two keys must always be set together to establish a valid
multi-account session.

# `put_primary_user_id`

```elixir
@spec put_primary_user_id(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Writes `"primary_user_id"` to the session.

# `put_session_token`

```elixir
@spec put_session_token(Plug.Conn.t(), String.t()) :: Plug.Conn.t()
```

Writes `"session_token"` to the session.

# `put_user_id`

```elixir
@spec put_user_id(Plug.Conn.t(), String.t(), String.t()) :: Plug.Conn.t()
```

Writes the user subject to the session `"user"` key.

Constructs the subject string from the given `user_id` using the format
`"<short_name>?id=<UUID>"`. The `short_name` parameter defaults to `"user"`,
matching the typical Ash resource short name for User resources. If your
resource uses a different `short_name`, pass it explicitly.

Only works with `Plug.Conn`.

---

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