# `Arc.Authentication`
[🔗](https://github.com/Cratis/Arc.Elixir/blob/main/lib/arc/authentication.ex#L4)

Authentication handlers turn an incoming request into an `Arc.Principal`.

Handlers run in the order configured on the application. The first handler that recognizes the
request decides:

  * `{:authenticated, principal}` - the chain stops with that principal
  * `:failed` - terminal; later handlers do not run and the caller gets a generic 401
  * `:anonymous` - this handler did not recognize the request; the next one tries. Anonymous
    is the final outcome only when no handler recognized the request.

Arc does not authenticate users itself. The default handler, `Arc.Authentication.FromAssigns`,
reads a principal your own plug assigned, so `phx.gen.auth`, token plugs and reverse proxies
keep working unchanged.

# `authenticate`

```elixir
@callback authenticate(Plug.Conn.t()) ::
  {:authenticated, Arc.Principal.t()} | :failed | :anonymous
```

---

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