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

Password management for Weavr users.

All paths confirmed against `api.weavr.io/products/multi/openapi`.

## Confirmed endpoints

  * `POST /passwords` — create a password for a user who doesn't have one
  * `POST /passwords/update` — update (change) an existing password
  * `POST /passwords/lost/send` — step 1: send a lost-password code to the user
  * `POST /passwords/lost/verify` — step 2: verify the code and set a new password

## Notes

  * `create/3` is used for new users (root or authorised) who have not yet
    set a password. If a corporate root user is a "single email, multiple
    identities" user, their `passwordAlreadySet` field in the create
    corporate response will be `true`, indicating no call to `create/3`
    is needed.
  * On Sandbox, the lost-password verification code is always `"123456"`.

# `create`

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

Creates a password for a new user who doesn't yet have one.

`POST /passwords` — requires the user's `auth_token`.

`attrs` should contain:
- `"newPassword"` — object with `"value"` (the new password string)

# `send_lost`

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

Step 1 of lost-password flow: sends a recovery code to the user's email.

`POST /passwords/lost/send` — uses `api-key` only (no `auth_token`).

`attrs` should contain `"email"`.

On Sandbox the code sent is always `"123456"`.

# `update`

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

Updates (changes) an existing user's password.

`POST /passwords/update`

`attrs` should contain:
- `"oldPassword"` — object with `"value"`
- `"newPassword"` — object with `"value"`

# `verify_lost`

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

Step 2 of lost-password flow: verifies the recovery code and sets a
new password.

`POST /passwords/lost/verify` — uses `api-key` only.

`attrs` should contain:
- `"email"`
- `"verificationCode"` — the code from `send_lost/2` (Sandbox: always `"123456"`)
- `"newPassword"` — object with `"value"`

---

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