Weavr.Auth (Weavr v1.0.0)

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:

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."
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.

Summary

Types

login_result()

token()

Functions

exchange_for_access_token(config, auth_token, identity_id)

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

list_identities(config, auth_token)

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

login_via_biometrics(config, payload)

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

login_with_password(config, credentials)

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

logout(config, auth_token)

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

step_up_required?(arg1)

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

Types

login_result()

@type login_result() :: %{
  :auth_token => token(),
  optional(:expires_in) => integer(),
  optional(:identities) => [map()],
  optional(:raw) => map()
}

token()

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

Functions

exchange_for_access_token(config, auth_token, identity_id)

@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(config, auth_token)

@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(config, payload)

@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(config, credentials)

@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(config, auth_token)

@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?(arg1)

@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.