# Accounts and sessions

> Sign-up, sign-in (password or emailed link), email confirmation, password reset and the profile.

Sign-up, sign-in (password or emailed link), email confirmation, password reset and the profile. Generated from the [OpenAPI spec](https://dev.mongrl.com/openapi.json). Each endpoint says which key it needs; see [Authentication](https://dev.mongrl.com/guides/authentication.md).

| Method | Path | What it does |
|---|---|---|
| POST | [`/v1/email-verifications`](#confirm-an-email-address-with-the-emailed-link) | Confirm an email address with the emailed link |
| GET | [`/v1/me`](#get-the-signed-in-user) | Get the signed-in user |
| PATCH | [`/v1/me`](#update-the-signed-in-users-profile) | Update the signed-in user's profile |
| POST | [`/v1/me/verification-email`](#send-the-email-confirmation-link-again) | Send the email confirmation link again |
| POST | [`/v1/password-resets`](#email-a-password-reset-link) | Email a password reset link |
| POST | [`/v1/password-resets/confirm`](#set-a-new-password-with-the-emailed-link) | Set a new password with the emailed link |
| POST | [`/v1/sessions`](#sign-in-with-email-and-password) | Sign in with email and password |
| DELETE | [`/v1/sessions/current`](#sign-out) | Sign out |
| POST | [`/v1/sessions/email-link`](#email-a-sign-in-link) | Email a sign-in link |
| POST | [`/v1/sessions/from-link`](#sign-in-with-an-emailed-link) | Sign in with an emailed link |
| POST | [`/v1/users`](#create-an-account) | Create an account |

## Confirm an email address with the emailed link

`POST /v1/email-verifications` · operation `confirmEmail`

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Body** (`application/json`): [TokenInputBody](#tokeninputbody)

**Responses:** `200` [UserBody](#userbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Get the signed-in user

`GET /v1/me` · operation `getMe`

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Responses:** `200` [UserBody](#userbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Update the signed-in user's profile

`PATCH /v1/me` · operation `updateMe`

Only the fields sent change.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Body** (`application/json`): [UpdateMeInputBody](#updatemeinputbody)

**Responses:** `200` [UserBody](#userbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Send the email confirmation link again

`POST /v1/me/verification-email` · operation `resendVerificationEmail`

Links to `<storefront>/<language>/auth/verify-email?token=…`. Does nothing if the address is already confirmed.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Responses:** `202` Accepted · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Email a password reset link

`POST /v1/password-resets` · operation `requestPasswordReset`

Sends a link to `<storefront>/<language>/auth/reset-password?token=…` if the address has an account. Always answers 202.

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Body** (`application/json`): [EmailInputBody](#emailinputbody)

**Responses:** `202` Accepted · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Set a new password with the emailed link

`POST /v1/password-resets/confirm` · operation `resetPassword`

Signs the user out everywhere; sign them in again with the new password.

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Body** (`application/json`): [ResetInputBody](#resetinputbody)

**Responses:** `204` No Content · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Sign in with email and password

`POST /v1/sessions` · operation `signIn`

After 10 wrong passwords in 15 minutes the account is locked for the rest of that time (429 with Retry-After).

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Body** (`application/json`): [SignInInputBody](#signininputbody)

**Responses:** `201` [SignedInOutputBody](#signedinoutputbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Sign out

`DELETE /v1/sessions/current` · operation `signOut`

Ends the session sent as X-User-Session.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Responses:** `204` No Content · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Email a sign-in link

`POST /v1/sessions/email-link` · operation `requestSignInLink`

Sends a link to `<storefront>/<language>/auth/sign-in?token=…` if the address has an account. Always answers 202, so it doesn't reveal who has one. At most 5 emails an hour per address.

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Body** (`application/json`): [EmailInputBody](#emailinputbody)

**Responses:** `202` Accepted · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Sign in with an emailed link

`POST /v1/sessions/from-link` · operation `signInWithLink`

The token from the link works once. Following the link also confirms the email address.

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Body** (`application/json`): [TokenInputBody](#tokeninputbody)

**Responses:** `201` [SignedInOutputBody](#signedinoutputbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Create an account

`POST /v1/users` · operation `signUp`

Creates the user and signs them in. Call from the shop's server.

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Body** (`application/json`): [SignUpInputBody](#signupinputbody)

**Responses:** `201` [SignedInOutputBody](#signedinoutputbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Schemas

Fields marked * are always present in responses and required in requests.

### TokenInputBody

| Field | Type | Notes |
|---|---|---|
| `token` * | string | From the emailed link's ?token=. max 200 chars |

### UserBody

| Field | Type | Notes |
|---|---|---|
| `bio` * | string | Public |
| `created_at` * | string (date-time) |  |
| `display_name` * | string |  |
| `email` * | string (email) |  |
| `email_verified` * | boolean |  |
| `first_name` * | string |  |
| `has_password` * | boolean |  |
| `id` * | string |  |
| `last_name` * | string |  |
| `locale` * | string | The user's language; empty means the marketplace's default |
| `phone` * | string | Private |

### UpdateMeInputBody

| Field | Type | Notes |
|---|---|---|
| `bio` | string | max 2000 chars |
| `display_name` | string | max 100 chars |
| `first_name` | string | max 100 chars |
| `last_name` | string | max 100 chars |
| `locale` | string | One of the marketplace's languages, or empty for its default |
| `phone` | string | max 40 chars |

### EmailInputBody

| Field | Type | Notes |
|---|---|---|
| `email` * | string | max 254 chars |

### ResetInputBody

| Field | Type | Notes |
|---|---|---|
| `password` * | string | max 128 chars |
| `token` * | string | From the emailed link's ?token=. max 200 chars |

### SignInInputBody

| Field | Type | Notes |
|---|---|---|
| `email` * | string | max 254 chars |
| `password` * | string | max 128 chars |

### SignedInOutputBody

| Field | Type | Notes |
|---|---|---|
| `session` * | [SessionBody](#sessionbody) |  |
| `user` * | [UserBody](#userbody) |  |

### SignUpInputBody

| Field | Type | Notes |
|---|---|---|
| `bio` | string | max 2000 chars |
| `display_name` | string | max 100 chars |
| `email` * | string (email) | max 254 chars |
| `first_name` | string | max 100 chars |
| `last_name` | string | max 100 chars |
| `locale` | string | One of the marketplace's languages |
| `password` | string | Optional: without one, the user signs in with emailed links. max 128 chars |
| `phone` | string | max 40 chars |

### SessionBody

| Field | Type | Notes |
|---|---|---|
| `expires_at` * | string (date-time) | Extended while the session is used |
| `token` * | string | Send as the X-User-Session header. Shown only here. |