# Client API: Authentication

> Register, login, refresh tokens, and manage your profile.

Source: https://www.coritan.com/docs/api/reference/client/authentication/

Register, login, refresh tokens, and manage your profile. Bearer auth uses the access JWT from login.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Client API reference](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/auth/forgot-password`](#op-post-api-v1-auth-forgot-password) | Issue a reset link by email |
| POST | [`/api/v1/auth/login`](#op-post-api-v1-auth-login) | Login |
| GET | [`/api/v1/auth/mailbox-availability`](#op-get-api-v1-auth-mailbox-availability) | Live check behind the sign-up form's username field |
| GET | [`/api/v1/auth/mailbox-domain`](#op-get-api-v1-auth-mailbox-domain) | Mailbox domain |
| GET | [`/api/v1/auth/me`](#op-get-api-v1-auth-me) | Get me |
| PUT | [`/api/v1/auth/me`](#op-put-api-v1-auth-me) | Update me |
| GET | [`/api/v1/auth/me/api-keys`](#op-get-api-v1-auth-me-api-keys) | List keys |
| POST | [`/api/v1/auth/me/api-keys`](#op-post-api-v1-auth-me-api-keys) | Create key |
| DELETE | [`/api/v1/auth/me/api-keys/{key_id}`](#op-delete-api-v1-auth-me-api-keys-key-id) | Revoke key |
| POST | [`/api/v1/auth/me/password`](#op-post-api-v1-auth-me-password) | Change password |
| GET | [`/api/v1/auth/me/staff-link`](#op-get-api-v1-auth-me-staff-link) | Get staff link |
| POST | [`/api/v1/auth/me/staff-link`](#op-post-api-v1-auth-me-staff-link) | Redeem staff link |
| DELETE | [`/api/v1/auth/me/staff-link`](#op-delete-api-v1-auth-me-staff-link) | Remove staff link |
| POST | [`/api/v1/auth/refresh`](#op-post-api-v1-auth-refresh) | Refresh |
| POST | [`/api/v1/auth/register`](#op-post-api-v1-auth-register) | Register |
| POST | [`/api/v1/auth/reset-password`](#op-post-api-v1-auth-reset-password) | Reset password |
| GET | [`/api/v1/auth/turnstile`](#op-get-api-v1-auth-turnstile) | Turnstile config |

### Issue a reset link by email {#op-post-api-v1-auth-forgot-password}

`POST /api/v1/auth/forgot-password`

Issue a reset link by email. The answer is the same whether or not the
address has an account, so the form cannot be used to probe for one.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (email) | yes |
| `turnstile_token` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Login {#op-post-api-v1-auth-login}

`POST /api/v1/auth/login`

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (email) | yes |
| `password` | string | yes |
| `turnstile_token` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Live check behind the sign-up form's username field {#op-get-api-v1-auth-mailbox-availability}

`GET /api/v1/auth/mailbox-availability`

Live check behind the sign-up form's username field.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `local_part` | query | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox domain {#op-get-api-v1-auth-mailbox-domain}

`GET /api/v1/auth/mailbox-domain`

Whether this storefront offers a mailbox on its own mail domain at
sign-up, and which domain. Public: the form reads it before anyone has an
account.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get me {#op-get-api-v1-auth-me}

`GET /api/v1/auth/me`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `company` | string or null |
| `status` | string |
| `billing_mode` | string |
| `credit_balance` | number |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `created_at` | string (date-time) |

### Update me {#op-put-api-v1-auth-me}

`PUT /api/v1/auth/me`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `company` | string or null |
| `status` | string |
| `billing_mode` | string |
| `credit_balance` | number |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `created_at` | string (date-time) |

### List keys {#op-get-api-v1-auth-me-api-keys}

`GET /api/v1/auth/me/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Default: `200`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].label` | string |
| `[].permissions` | array of string or null |
| `[].ip_whitelist` | array of string or null |
| `[].is_active` | boolean |
| `[].last_used_at` | string (date-time) or null |
| `[].created_at` | string (date-time) |

### Create key {#op-post-api-v1-auth-me-api-keys}

`POST /api/v1/auth/me/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | yes |
| `permissions` | array of string or null | no |
| `ip_whitelist` | array of string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `label` | string |
| `permissions` | array of string or null |
| `ip_whitelist` | array of string or null |
| `is_active` | boolean |
| `last_used_at` | string (date-time) or null |
| `created_at` | string (date-time) |
| `raw_key` | string |

### Revoke key {#op-delete-api-v1-auth-me-api-keys-key-id}

`DELETE /api/v1/auth/me/api-keys/{key_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `key_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Change password {#op-post-api-v1-auth-me-password}

`POST /api/v1/auth/me/password`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `current_password` | string | yes |
| `new_password` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get staff link {#op-get-api-v1-auth-me-staff-link}

`GET /api/v1/auth/me/staff-link`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Redeem staff link {#op-post-api-v1-auth-me-staff-link}

`POST /api/v1/auth/me/staff-link`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove staff link {#op-delete-api-v1-auth-me-staff-link}

`DELETE /api/v1/auth/me/staff-link`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Refresh {#op-post-api-v1-auth-refresh}

`POST /api/v1/auth/refresh`

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `refresh_token` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `access_token` | string |
| `refresh_token` | string |
| `token_type` | string |
| `expires_in` | integer |

### Register {#op-post-api-v1-auth-register}

`POST /api/v1/auth/register`

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (email) or null | no |
| `mailbox_local_part` | string or null | no |
| `recovery_email` | string (email) or null | no |
| `password` | string | yes |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `turnstile_token` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `access_token` | string |
| `refresh_token` | string |
| `token_type` | string |
| `expires_in` | integer |

### Reset password {#op-post-api-v1-auth-reset-password}

`POST /api/v1/auth/reset-password`

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `token` | string | yes |
| `new_password` | string | yes |
| `turnstile_token` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Turnstile config {#op-get-api-v1-auth-turnstile}

`GET /api/v1/auth/turnstile`

Public: whether the platform's auth and order forms must render the
Turnstile widget, and with which site key (no auth).

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |