# Organization API: Customer Authentication: Auth

> The 25 Organization API operations for auth.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-authentication/auth/

Part of [Customer Authentication](/docs/api/reference/organizations/customer-authentication/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/auth/forgot-password`](#op-post-api-v1-orgs-org-slug-auth-forgot-password) | Issue a password-reset token stored on the customer metadata |
| POST | [`/api/v1/orgs/{org_slug}/auth/login`](#op-post-api-v1-orgs-org-slug-auth-login) | Password sign-in with an email address or a username |
| POST | [`/api/v1/orgs/{org_slug}/auth/logout`](#op-post-api-v1-orgs-org-slug-auth-logout) | Revoke the current access token (and its refresh twin if present) |
| GET | [`/api/v1/orgs/{org_slug}/auth/me`](#op-get-api-v1-orgs-org-slug-auth-me) | Customer profile |
| PATCH | [`/api/v1/orgs/{org_slug}/auth/me`](#op-patch-api-v1-orgs-org-slug-auth-me) | Update customer profile |
| GET | [`/api/v1/orgs/{org_slug}/auth/mfa`](#op-get-api-v1-orgs-org-slug-auth-mfa) | Customer MFA status |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/disable`](#op-post-api-v1-orgs-org-slug-auth-mfa-disable) | Turn the factor off with a current code, and with the password when the account has one |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/enable`](#op-post-api-v1-orgs-org-slug-auth-mfa-enable) | Customer MFA enable |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/recovery-codes`](#op-post-api-v1-orgs-org-slug-auth-mfa-recovery-codes) | Customer MFA regenerate recovery codes |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/setup`](#op-post-api-v1-orgs-org-slug-auth-mfa-setup) | Customer MFA setup |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/verify`](#op-post-api-v1-orgs-org-slug-auth-mfa-verify) | Customer MFA verify |
| GET | [`/api/v1/orgs/{org_slug}/auth/oauth/connections`](#op-get-api-v1-orgs-org-slug-auth-oauth-connections) | List OAuth connections |
| DELETE | [`/api/v1/orgs/{org_slug}/auth/oauth/connections/{provider}`](#op-delete-api-v1-orgs-org-slug-auth-oauth-connections-provider) | Disconnect OAuth provider |
| GET | [`/api/v1/orgs/{org_slug}/auth/oauth/providers`](#op-get-api-v1-orgs-org-slug-auth-oauth-providers) | Public: which social providers are configured for storefront login |
| POST | [`/api/v1/orgs/{org_slug}/auth/oauth/set-password`](#op-post-api-v1-orgs-org-slug-auth-oauth-set-password) | OAuth set password |
| GET | [`/api/v1/orgs/{org_slug}/auth/oauth/{provider}/authorize`](#op-get-api-v1-orgs-org-slug-auth-oauth-provider-authorize) | OAuth authorize |
| GET | [`/api/v1/orgs/{org_slug}/auth/oauth/{provider}/callback`](#op-get-api-v1-orgs-org-slug-auth-oauth-provider-callback) | OAuth callback |
| POST | [`/api/v1/orgs/{org_slug}/auth/refresh`](#op-post-api-v1-orgs-org-slug-auth-refresh) | Customer refresh token |
| POST | [`/api/v1/orgs/{org_slug}/auth/register`](#op-post-api-v1-orgs-org-slug-auth-register) | Self-service customer signup for the org storefront |
| POST | [`/api/v1/orgs/{org_slug}/auth/resend-verification`](#op-post-api-v1-orgs-org-slug-auth-resend-verification) | Send another confirmation link to the signed-in customer's own address |
| POST | [`/api/v1/orgs/{org_slug}/auth/reset-password`](#op-post-api-v1-orgs-org-slug-auth-reset-password) | Customer reset password |
| GET | [`/api/v1/orgs/{org_slug}/auth/sessions`](#op-get-api-v1-orgs-org-slug-auth-sessions) | Where this account is currently signed in |
| POST | [`/api/v1/orgs/{org_slug}/auth/sessions/revoke-others`](#op-post-api-v1-orgs-org-slug-auth-sessions-revoke-others) | Sign out everywhere except here |
| GET | [`/api/v1/orgs/{org_slug}/auth/username-available`](#op-get-api-v1-orgs-org-slug-auth-username-available) | Whether a username can be taken at signup, and why not when it cannot |
| POST | [`/api/v1/orgs/{org_slug}/auth/verify-email`](#op-post-api-v1-orgs-org-slug-auth-verify-email) | Confirm an address from an emailed link |

### Issue a password-reset token stored on the customer metadata {#op-post-api-v1-orgs-org-slug-auth-forgot-password}

`POST /api/v1/orgs/{org_slug}/auth/forgot-password`

Issue a password-reset token stored on the customer metadata.
Always returns success to avoid email enumeration.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

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

#### Responses

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

### Password sign-in with an email address or a username {#op-post-api-v1-orgs-org-slug-auth-login}

`POST /api/v1/orgs/{org_slug}/auth/login`

Password sign-in with an email address or a username.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `identifier` | string or null | no |
| `email` | string or null | no |
| `username` | string or null | no |
| `password` | string | yes |

#### Responses

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

### Revoke the current access token (and its refresh twin if present) {#op-post-api-v1-orgs-org-slug-auth-logout}

`POST /api/v1/orgs/{org_slug}/auth/logout`

Revoke the current access token (and its refresh twin if present).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

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

### Customer profile {#op-get-api-v1-orgs-org-slug-auth-me}

`GET /api/v1/orgs/{org_slug}/auth/me`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `chat_handle` | string or null |
| `chat_handle_locked_for` | integer |
| `company` | string or null |
| `phone` | string or null |
| `status` | string |
| `credit_balance` | string |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `custom_fields` | object or null |
| `last_login_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `has_password` | boolean |
| `staff_member` | boolean |
| `email_verified` | boolean |
| `avatar_url` | string or null |

### Update customer profile {#op-patch-api-v1-orgs-org-slug-auth-me}

`PATCH /api/v1/orgs/{org_slug}/auth/me`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `chat_handle` | string or null | no |
| `company` | string or null | no |
| `phone` | string or null | no |
| `password` | string or null | no |
| `current_password` | 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 |
| `org_id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `chat_handle` | string or null |
| `chat_handle_locked_for` | integer |
| `company` | string or null |
| `phone` | string or null |
| `status` | string |
| `credit_balance` | string |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `custom_fields` | object or null |
| `last_login_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `has_password` | boolean |
| `staff_member` | boolean |
| `email_verified` | boolean |
| `avatar_url` | string or null |

### Customer MFA status {#op-get-api-v1-orgs-org-slug-auth-mfa}

`GET /api/v1/orgs/{org_slug}/auth/mfa`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

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

### Turn the factor off with a current code, and with the password when the account has one {#op-post-api-v1-orgs-org-slug-auth-mfa-disable}

`POST /api/v1/orgs/{org_slug}/auth/mfa/disable`

Turn the factor off with a current code, and with the password when the
account has one. Refused while the brand requires a factor of everyone.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |
| `code` | string | yes |

#### Responses

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

### Customer MFA enable {#op-post-api-v1-orgs-org-slug-auth-mfa-enable}

`POST /api/v1/orgs/{org_slug}/auth/mfa/enable`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

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

### Customer MFA regenerate recovery codes {#op-post-api-v1-orgs-org-slug-auth-mfa-recovery-codes}

`POST /api/v1/orgs/{org_slug}/auth/mfa/recovery-codes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

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

### Customer MFA setup {#op-post-api-v1-orgs-org-slug-auth-mfa-setup}

`POST /api/v1/orgs/{org_slug}/auth/mfa/setup`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

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

### Customer MFA verify {#op-post-api-v1-orgs-org-slug-auth-mfa-verify}

`POST /api/v1/orgs/{org_slug}/auth/mfa/verify`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

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

### List OAuth connections {#op-get-api-v1-orgs-org-slug-auth-oauth-connections}

`GET /api/v1/orgs/{org_slug}/auth/oauth/connections`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### 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 |
| --- | --- |
| `[].provider` | string |
| `[].provider_username` | string or null |
| `[].provider_email` | string or null |
| `[].provider_avatar` | string or null |
| `[].created_at` | string (date-time) or null |

### Disconnect OAuth provider {#op-delete-api-v1-orgs-org-slug-auth-oauth-connections-provider}

`DELETE /api/v1/orgs/{org_slug}/auth/oauth/connections/{provider}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `provider` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

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

### Public: which social providers are configured for storefront login {#op-get-api-v1-orgs-org-slug-auth-oauth-providers}

`GET /api/v1/orgs/{org_slug}/auth/oauth/providers`

Public: which social providers are configured for storefront login.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `providers` | array of string |

### OAuth set password {#op-post-api-v1-orgs-org-slug-auth-oauth-set-password}

`POST /api/v1/orgs/{org_slug}/auth/oauth/set-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

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

#### Responses

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

### OAuth authorize {#op-get-api-v1-orgs-org-slug-auth-oauth-provider-authorize}

`GET /api/v1/orgs/{org_slug}/auth/oauth/{provider}/authorize`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `provider` | path | string | yes |

#### Responses

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

### OAuth callback {#op-get-api-v1-orgs-org-slug-auth-oauth-provider-callback}

`GET /api/v1/orgs/{org_slug}/auth/oauth/{provider}/callback`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `provider` | path | string | yes |
| `code` | query | string or null | no |
| `state` | query | string or null | no |
| `error` | query | string or null | no |

#### Responses

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

### Customer refresh token {#op-post-api-v1-orgs-org-slug-auth-refresh}

`POST /api/v1/orgs/{org_slug}/auth/refresh`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | 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 |
| `scopes` | array of string or null |

### Self-service customer signup for the org storefront {#op-post-api-v1-orgs-org-slug-auth-register}

`POST /api/v1/orgs/{org_slug}/auth/register`

Self-service customer signup for the org storefront.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string | yes |
| `password` | string | yes |
| `username` | string or null | no |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `phone` | string or null | no |
| `turnstile_token` | string or null | no |

#### Responses

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

### Send another confirmation link to the signed-in customer's own address {#op-post-api-v1-orgs-org-slug-auth-resend-verification}

`POST /api/v1/orgs/{org_slug}/auth/resend-verification`

Send another confirmation link to the signed-in customer's own address.

Authenticated rather than taking an email in the body: an anonymous version
would let anyone post mail to any address on this org's behalf, and there is
nothing to gain from it when the customer can already sign in.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

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

### Customer reset password {#op-post-api-v1-orgs-org-slug-auth-reset-password}

`POST /api/v1/orgs/{org_slug}/auth/reset-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `token` | string | yes |
| `password` | string | yes |

#### Responses

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

### Where this account is currently signed in {#op-get-api-v1-orgs-org-slug-auth-sessions}

`GET /api/v1/orgs/{org_slug}/auth/sessions`

Where this account is currently signed in.

The token row already records the address and user agent it was issued to,
so a customer can see a session they do not recognise without us keeping a
second log of it. Tokens are never returned, only the hash we match the
caller's own session on. ``country_code`` is where the address places
(see ``_session_countries``), or null when nothing can place it, so the
page can say "Germany · 203.0.113.9" rather than an address alone.

Support sessions are labelled rather than hidden. An admin looking at an
account shows up here as a sign-in from an address the customer will not
recognise, and the honest answer to that is to say what it is.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

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

### Sign out everywhere except here {#op-post-api-v1-orgs-org-slug-auth-sessions-revoke-others}

`POST /api/v1/orgs/{org_slug}/auth/sessions/revoke-others`

Sign out everywhere except here.

The one action worth having after a shared or stolen laptop, and it must
not log the customer out of the browser asking for it, so the presented
token is the one row left alone.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

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

### Whether a username can be taken at signup, and why not when it cannot {#op-get-api-v1-orgs-org-slug-auth-username-available}

`GET /api/v1/orgs/{org_slug}/auth/username-available`

Whether a username can be taken at signup, and why not when it cannot.

Public, because the signup form asks while somebody is still typing and has
no session yet. It gives away nothing the community pages do not: a handle
is the name everyone already sees above every message its owner posts.
Answers rather than raising, so a 422 per keystroke is not the shape of it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `username` | query | string | yes |

#### Responses

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

### Confirm an address from an emailed link {#op-post-api-v1-orgs-org-slug-auth-verify-email}

`POST /api/v1/orgs/{org_slug}/auth/verify-email`

Confirm an address from an emailed link.

Public, because the customer may follow the link in a browser that is not
signed in. The token is the credential, and it only ever sets a flag
nothing reads for access.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `customer_id` | integer | yes |
| `token` | string | yes |

#### Responses

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