> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth Endpoints

> User authentication, registration, email verification, 2FA, and account management

> **Source:** `equa-server/modules/api/src/endpoints/auth-endpoints.ts`

# Auth Endpoints

Endpoints for user authentication, registration, password reset, email verification, two-factor authentication, and account management.

**Endpoint count:** 19 (12 public, 7 authenticated)

## Public Endpoints

These endpoints do not require an active session.

### Get Current User

```
GET /v1/user/current
```

| Field        | Value                                           |
| ------------ | ----------------------------------------------- |
| Auth         | Optional (returns null user if unauthenticated) |
| Request Type | `EmptyRequest`                                  |

Returns the current authenticated user, or an unauthenticated response if no valid session exists.

### Get Current User (Deprecated)

```
GET /v1/user
```

<Warning>
  **Deprecated.** Use [`GET /v1/user/current`](#get-current-user) instead.
  This endpoint will be removed in a future API version.
</Warning>

| Field        | Value                                           |
| ------------ | ----------------------------------------------- |
| Auth         | Optional (returns null user if unauthenticated) |
| Request Type | `EmptyRequest`                                  |

Legacy endpoint that returns the same response as `GET /v1/user/current`.

**Response:**

```json theme={null}
{
  "id": "uuid",
  "email": "user@example.com",
  "username": "jdoe",
  "firstName": "Jane",
  "lastName": "Doe",
  "emailVerified": true,
  "twoFactorEnabled": false
}
```

***

### Login

```
POST /v1/user/login
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Authenticate with email and password. Sets a session cookie on success.

**Request:**

```json theme={null}
{
  "email": "user@example.com",
  "password": "your-password"
}
```

**Response:** The authenticated user object.

***

### Google OAuth Login

```
POST /v1/user/google-auth
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Authenticate using a Google OAuth ID token. Creates or links a user account and establishes a session.

**Request:**

```json theme={null}
{
  "token": "google-id-token"
}
```

**Response:** The authenticated user object.

***

### Register

```
POST /v1/user
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Create a new user account. The registration endpoint captures the client IP via `request-ip` middleware and enforces the `REGISTRATION_IP_LIMIT` (default 20 per IP).

**Request:**

```json theme={null}
{
  "email": "user@example.com",
  "password": "secure-password",
  "username": "jdoe",
  "firstName": "Jane",
  "lastName": "Doe",
  "couponCode": "OPTIONAL_COUPON"
}
```

**Response:** The newly created user object.

***

### Check Email Availability

```
POST /v1/user/email/available
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Check whether an email address is available for registration.

**Request:**

```json theme={null}
{
  "email": "user@example.com"
}
```

**Response:**

```json theme={null}
{
  "available": true
}
```

***

### Check Username Availability

```
POST /v1/user/username/available
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Check whether a username is available for registration.

**Request:**

```json theme={null}
{
  "username": "jdoe"
}
```

**Response:**

```json theme={null}
{
  "available": true
}
```

***

### Reset Password

```
POST /v1/user/password/reset
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Send a password reset email to the specified username or email address.

**Request:**

```json theme={null}
{
  "usernameOrEmail": "user@example.com"
}
```

***

### Verify Email

```
POST /v1/user/email/verify
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Verify an email address using a verification code received via email.

**Request:**

```json theme={null}
{
  "code": "verification-code"
}
```

***

### Resend Verification Email

```
POST /v1/user/email/verify/send
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Resend the email verification message. Throttled by `EMAIL_VERIFICATION_LIMIT_SECONDS` (default 1800s / 30 minutes).

**Request:**

```json theme={null}
{
  "usernameOrEmail": "user@example.com"
}
```

***

### Generate 2FA Secret

```
GET /v1/user/2fa
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Generate a new TOTP two-factor authentication secret and QR code for setup.

***

### Verify 2FA Token

```
POST /v1/user/2fa/verify
```

| Field | Value |
| ----- | ----- |
| Auth  | None  |

Verify a TOTP token against a 2FA secret during setup.

**Request:**

```json theme={null}
{
  "token": "123456",
  "secret": "base32-secret"
}
```

***

## Authenticated Endpoints

These endpoints require an active session.

### Enable 2FA

```
POST /v1/user/2fa
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Enable two-factor authentication on the authenticated user's account after successful token verification.

**Request:**

```json theme={null}
{
  "token": "123456",
  "secret": "base32-secret"
}
```

***

### Update User Profile

```
PATCH /v1/user
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Update the current user's profile information.

**Request:**

```json theme={null}
{
  "firstName": "Jane",
  "lastName": "Doe",
  "username": "janedoe"
}
```

***

### List Users

```
GET /v1/users
```

| Field      | Value         |
| ---------- | ------------- |
| Auth       | Required      |
| Permission | `canReadSite` |

List all users (site admin only).

***

### Logout

```
POST /v1/user/logout
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Destroy the current session and clear the session cookie.

***

### Get User Coupon

```
GET /v1/user/coupon
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Get coupon information for the authenticated user.

***

### Update User Account

```
PATCH /v1/user/:user/account
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Update account-level settings for the specified user.

***

### Get User Account

```
GET /v1/user/:user/account
```

| Field | Value    |
| ----- | -------- |
| Auth  | Required |

Retrieve account-level details for the specified user.