Accounts and sign-in

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

Sign up

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).
• 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

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.
• The marketplace’s team has set the shop’s address in the console (Settings → Shop and emails), so emailed links point at your site.