# `Weavr.Auth`
[🔗](https://github.com/iamkanishka/weavr/blob/main/lib/weavr/auth.ex#L1)

Authentication and session token handling for the Weavr Multi API.

## The Weavr token model

Weavr's authentication model has two materially different tokens,
which is easy to miss if you only skim a single endpoint's docs:

1. **Auth Token** — returned directly by `login_with_password/2` or
   `login_via_biometrics/2`. It identifies *the user* and *the method*
   they authenticated with (password, passcode, biometrics), but on
   its own "unlocks very limited functionality."

2. **Access Token** — obtained by exchanging an Auth Token via
   `exchange_for_access_token/3`. It carries the additional piece of
   information the Auth Token is missing: *which identity* (which
   Corporate or Consumer) the user wants to act as. This matters
   specifically for embedders who have enabled a root user being
   linked to multiple Corporates/Consumers, where a single
   email+password login can switch between several identities
   without a fresh login.

Throughout most of the Weavr API reference, the token concept is
called `auth_token` — but it is sent as `Authorization: Bearer <token>`
in the HTTP header, alongside `api-key`. This is confirmed across all
Weavr's published curl examples for the Multi API.
**If your embedder configuration does not use multi-identity root
users or biometrics, the Auth Token returned at login is generally
sufficient and you can skip the exchange step.** If you're unsure
which applies to your account, check your Weavr embedder
configuration or ask your Weavr integration contact — this client
cannot determine that for you.

## Step-up authentication (SCA / PSD2)

Certain operations require Strong Customer Authentication under
PSD2. When the API responds with a step-up challenge, the end user
completes an SCA-compliant multi-factor challenge out of band, which
yields a *stepped-up* Auth/Access Token. This module exposes
`step_up_required?/1` and `stepped_up?/1` helpers to inspect a
`Weavr.Error.API` for this condition; actually presenting the
challenge to the user is application-specific and outside what an
HTTP client can do for you.

This module is intentionally low-level (plain functions over a
`Weavr.Config`). For session-state management (holding onto the
current token across calls), see `Weavr.Client`.

# `login_result`

```elixir
@type login_result() :: %{
  :auth_token =&gt; token(),
  optional(:expires_in) =&gt; integer(),
  optional(:identities) =&gt; [map()],
  optional(:raw) =&gt; map()
}
```

# `token`

```elixir
@type token() :: String.t()
```

# `exchange_for_access_token`

```elixir
@spec exchange_for_access_token(Weavr.Config.t(), token(), String.t()) ::
  {:ok, login_result()} | {:error, Weavr.Error.t()}
```

Exchanges an Auth Token for an Access Token scoped to a specific
identity.

This is the step described in the moduledoc as required for
multi-identity root users (and recommended generally, if your
embedder configuration calls for it). `identity_id` is one of the
ids returned by `list_identities/2`.

Sends `POST /access_token`.

# `list_identities`

```elixir
@spec list_identities(Weavr.Config.t(), token()) ::
  {:ok, [map()]} | {:error, Weavr.Error.t()}
```

Lists the identities (Corporates/Consumers) the current Auth Token's
user can access.

Sends `GET /identities`. Relevant for embedders using the
multi-identity root user feature — use this to discover which
identity ids are available to pass to `exchange_for_access_token/3`.

# `login_via_biometrics`

```elixir
@spec login_via_biometrics(Weavr.Config.t(), map()) ::
  {:ok, login_result()} | {:error, Weavr.Error.t()}
```

Authenticates a user via a biometric assertion previously registered
with Weavr.

Sends `POST /login_via_biometrics`. The exact assertion payload
depends on your mobile biometric integration (Face ID / Touch ID /
Android biometric prompt); consult your Weavr onboarding docs for
the expected shape, since this varies by platform and is not fully
specified in the fragments of the spec available to this client. The
`payload` map is passed through as the request body unmodified.

# `login_with_password`

```elixir
@spec login_with_password(Weavr.Config.t(), keyword() | map()) ::
  {:ok, login_result()} | {:error, Weavr.Error.t()}
```

Authenticates a user with the email and password they provided when
registering.

Sends `POST /login_with_password` with the account's `api-key`
header. On success, returns the Auth Token plus any additional
fields Weavr includes in the response (e.g. available identities,
for multi-identity root users).

## Examples

    {:ok, %{auth_token: token}} =
      Weavr.Auth.login_with_password(config, email: "user@example.com", password: "secret")

# `logout`

```elixir
@spec logout(Weavr.Config.t(), token()) :: {:ok, term()} | {:error, Weavr.Error.t()}
```

Logs the user out, invalidating the given Auth/Access Token
server-side.

Sends `POST /logout`. Always returns `:ok` for the local side effect
of forgetting the token even if you discard the result — but
checking the result lets you confirm the server-side session was
actually invalidated, which matters if you're logging out due to a
security event.

# `step_up_required?`

```elixir
@spec step_up_required?(Weavr.Error.API.t()) :: boolean()
```

Inspects a `Weavr.Error.API` to determine whether it represents a
PSD2 / SCA step-up authentication challenge rather than a plain
authorization failure.

Weavr's documented step-up flow returns a challenge that the end
user must complete out-of-band (passcode, biometrics, OTP, etc.);
the exact response shape for the challenge itself is
account/configuration-specific and not fully available to this
client, so this helper only recognizes the common
`code == "STEP_UP_REQUIRED"` / `status == 403` with a step-up code
pattern. If your account returns a different shape, match on
`error.body` directly.

---

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