# Accounts and sign-in

> Sign-up, sign-in with a password or an emailed link, email confirmation, password reset and the profile.

Buyers and sellers share one kind of account. People can use a password, emailed sign-in links, or both. All of these calls come from your server with your secret key ([Authentication](https://dev.mongrl.com/guides/authentication.md)).

## Sign up

```http
POST /v1/users
{ "email": "mia@example.com", "password": "correct horse battery", "first_name": "Mia", "locale": "sv" }
```

- The answer is `201` with `user` and `session`: they're signed in. Store the session ([how](https://dev.mongrl.com/guides/authentication.md#user-sessions)).
- `password` is optional. Without one, the user signs in with emailed links. Passwords are 8 to 128 characters.
- `locale` is one of the marketplace's languages (`GET /v1/marketplace` → `locales`). Emails go out in it.
- mongrl emails a link to confirm the address. Until then `user.email_verified` is `false`; buying and selling still work.
- An address already in use gives `409`.

## Sign in with a password

```http
POST /v1/sessions
{ "email": "mia@example.com", "password": "correct horse battery" }
```

After 10 wrong passwords in 15 minutes the account is locked for the rest of that window: `429` with a `Retry-After` header. Show the problem's `detail`.

## Sign in with an emailed link

1. `POST /v1/sessions/email-link` with `{ "email": "…" }`. It always answers `202`, so it never reveals who has an account. At most 5 emails an hour go to one address.
2. mongrl emails a link to **your** page: `https://<your shop>/<lang>/auth/sign-in?token=…`.
3. That page sends the token: `POST /v1/sessions/from-link` with `{ "token": "…" }`. The answer is `user` and `session`.

Links work once and for 15 minutes. Following one also confirms the email address. A used or expired link gives `422`: offer to send a new one. A blocked user gets `403`. Accounts the marketplace's team creates in the console get a welcome email with the same kind of link, valid for 7 days.

## Confirm the email address

The confirmation link goes to `https://<your shop>/<lang>/auth/verify-email?token=…`. That page calls `POST /v1/email-verifications` with `{ "token": "…" }`. Links last 24 hours; `POST /v1/me/verification-email` sends a new one to the signed-in user.

## Reset a password

1. `POST /v1/password-resets` with `{ "email": "…" }`. Always `202`.
2. The link goes to `https://<your shop>/<lang>/auth/reset-password?token=…` and lasts an hour.
3. That page asks for the new password and calls `POST /v1/password-resets/confirm` with `{ "token": "…", "password": "…" }`.

A reset signs the user out everywhere. Sign them in again with the new password.

## The profile

- `GET /v1/me` returns the signed-in user: name, email, `email_verified`, `has_password`, `locale`, `bio`, `phone`.
- `PATCH /v1/me` changes only the fields you send.
- `display_name` and `bio` are public (shown with a seller's listings); `phone` is private.

## Sign out

`DELETE /v1/sessions/current` with the user's session, then clear your cookie.

## Checklist

- [ ] Sign-up, sign-in and sign-out pages, plus "email me a link".
- [ ] `/<lang>/auth/sign-in`, `/<lang>/auth/verify-email` and `/<lang>/auth/reset-password` read `?token=` and call the API. See [Pages your shop needs](https://dev.mongrl.com/guides/storefront-pages.md).
- [ ] The marketplace's team has set the shop's address in the console (**Settings → Shop and emails**), so emailed links point at your site.