<!--
This file was generated by Spark. Do not edit it by hand.
-->
# DSL: AshAuthentication.AddOn.Confirmation

Confirmation support.

Sometimes when creating a new user, or changing a sensitive attribute (such as
their email address) you may want to wait for the user to confirm by way of
sending them a confirmation token to prove that it was really them that took
the action.

In order to add confirmation to your resource, it must been the following
minimum requirements:

1. Have a primary key
2. Have at least one attribute you wish to confirm
3. Tokens must be enabled

## Example

```elixir
defmodule MyApp.Accounts.User do
  use Ash.Resource,
    extensions: [AshAuthentication]

  attributes do
    uuid_primary_key :id
    attribute :email, :ci_string, allow_nil?: false
  end

  authentication do
    api MyApp.Accounts

    add_ons do
      confirmation :confirm do
        monitor_fields [:email]
        sender MyApp.ConfirmationSender
      end
    end

    strategies do
      # ...
    end
  end

  identities do
    identity :email, [:email] do
      eager_check_with MyApp.Accounts
    end
  end
end
```

## Attributes

A `confirmed_at` attribute will be added to your resource if it's not already
present (see `confirmed_at_field` in the DSL documentation).

## Actions

By default confirmation will add an action which updates the `confirmed_at`
attribute as well as retrieving previously stored changes and applying them to
the resource.

If you wish to perform the confirm action directly from your code you can do
so via the `AshAuthentication.Strategy` protocol.

### Example

    iex> strategy = Info.strategy!(Example.User, :confirm)
    ...> {:ok, user} = Strategy.action(strategy, :confirm, %{"confirm" => confirmation_token()})
    ...> user.confirmed_at >= one_second_ago()
    true

## Plugs

Confirmation provides a single endpoint for the `:confirm` phase.  If you wish
to interact with the plugs directly, you can do so via the
`AshAuthentication.Strategy` protocol.

### Example

    iex> strategy = Info.strategy!(Example.User, :confirm)
    ...> conn = conn(:get, "/user/confirm", %{"confirm" => confirmation_token()})
    ...> conn = Strategy.plug(strategy, :confirm, conn)
    ...> {_conn, {:ok, user}} = Plug.Helpers.get_authentication_result(conn)
    ...> user.confirmed_at >= one_second_ago()
    true


## authentication.add_ons.confirmation
```elixir
confirmation name \\ :confirm
```


User confirmation flow


### Arguments

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#authentication-add_ons-confirmation-name){: #authentication-add_ons-confirmation-name .spark-required} | `atom` |  | Uniquely identifies the add-on. |
### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`monitor_fields`](#authentication-add_ons-confirmation-monitor_fields){: #authentication-add_ons-confirmation-monitor_fields .spark-required} | `list(atom)` |  | A list of fields to monitor for changes. Confirmation will be sent when one of these fields are changed. |
| [`sender`](#authentication-add_ons-confirmation-sender){: #authentication-add_ons-confirmation-sender .spark-required} | `(any, any, any -> any) \| module` |  | How to send the confirmation instructions to the user. |
| [`token_lifetime`](#authentication-add_ons-confirmation-token_lifetime){: #authentication-add_ons-confirmation-token_lifetime } | `pos_integer \| {pos_integer, :days \| :hours \| :minutes \| :seconds}` | `{3, :days}` | How long should the confirmation token be valid.  If no unit is provided, then hours is assumed. |
| [`confirmed_at_field`](#authentication-add_ons-confirmation-confirmed_at_field){: #authentication-add_ons-confirmation-confirmed_at_field } | `atom` | `:confirmed_at` | The name of the field to store the time that the last confirmation took place. Created if it does not exist. |
| [`confirm_on_create?`](#authentication-add_ons-confirmation-confirm_on_create?){: #authentication-add_ons-confirmation-confirm_on_create? } | `boolean` | `true` | Generate and send a confirmation token when a new resource is created. Triggers when a create action is executed _and_ one of the monitored fields is being set. |
| [`confirm_on_update?`](#authentication-add_ons-confirmation-confirm_on_update?){: #authentication-add_ons-confirmation-confirm_on_update? } | `boolean` | `true` | Generate and send a confirmation token when a resource is changed.  Triggers when an update action is executed _and_ one of the monitored fields is being set. |
| [`inhibit_updates?`](#authentication-add_ons-confirmation-inhibit_updates?){: #authentication-add_ons-confirmation-inhibit_updates? } | `boolean` | `true` | Whether or not to wait until confirmation is received before actually changing a monitored field. See [the confirmation guide](/documentation/topics/confirmation.md) for more. |
| [`confirm_action_name`](#authentication-add_ons-confirmation-confirm_action_name){: #authentication-add_ons-confirmation-confirm_action_name } | `atom` | `:confirm` | The name of the action to use when performing confirmation. Will be created if it does not already exist. |


### Introspection

Target: `AshAuthentication.AddOn.Confirmation`


<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>