# User API

Account settings and email identity

Manage the authenticated user's account settings. Retrieve email-only identity, schedule deletion, export data, and manage marketing email preferences.

## Available Endpoints

| Method   | Endpoint                                                   | Description               |
| -------- | ---------------------------------------------------------- | ------------------------- |
| `GET`    | [`/api/user/me`](#get-apiuserme)                           | Get current user account  |
| `DELETE` | [`/api/user/me`](#delete-apiuserme)                        | Schedule account deletion |
| `GET`    | [`/api/user/me/export`](#get-apiusermeexport)              | Export user data          |
| `GET`    | [`/api/user/me/login-history`](#get-apiusermeloginhistory) | Get login history         |

## Endpoints

### GET /api/user/me

Get current user account

Retrieve the authenticated user's account information. Product identity is email-only.

**Auth:** bearer · **Scopes:** `user:read`

#### Request example

**curl**

```bash
curl -X GET "https://api.indexhog.com/api/user/me" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/user/me", {
method: "GET",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);
```

#### Response `200` — User account retrieved successfully

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "id": "507f1f77bcf86cd799439011",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "email": "john@example.com",
  "isVerified": true,
  "verifiedAt": "2024-01-01T00:05:00.000Z",
  "isActive": true,
  "lastLoginAt": "2024-01-15T09:00:00.000Z",
  "emailPreferences": {
    "marketingOptOut": false
  },
  "twoFactorEnabled": true,
  "organizationCount": 1,
  "role": "user"
}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```

### DELETE /api/user/me

Schedule account deletion

Soft-deletes the authenticated user's account with a 30-day grace period, then returns when it is scheduled for permanent deletion. Recoverable within the window. No request body — the client-side type-to-confirm gate is the confirmation, so this works for password and SSO/passwordless accounts alike.

**Auth:** bearer · **Scopes:** `user:write`

#### Request example

**curl**

```bash
curl -X DELETE "https://api.indexhog.com/api/user/me" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/user/me", {
method: "DELETE",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);
```

#### Response `200` — Account scheduled for deletion

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "deletionScheduledFor": "2024-02-15T00:00:00.000Z",
  "message": "string"
}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```

### GET /api/user/me/export

Export user data

Export all user data for GDPR compliance. Returns a JSON file with all user data.

**Auth:** bearer · **Scopes:** `user:read`

#### Request example

**curl**

```bash
curl -X GET "https://api.indexhog.com/api/user/me/export" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/user/me/export", {
method: "GET",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);
```

#### Response `200` — User data exported successfully

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {}
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```

### GET /api/user/me/login-history

Get login history

Get the authenticated user's login history.

**Auth:** bearer · **Scopes:** `user:read`

#### Request example

**curl**

```bash
curl -X GET "https://api.indexhog.com/api/user/me/login-history" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"
```

**JavaScript**

```javascript
const response = await fetch("https://api.indexhog.com/api/user/me/login-history", {
method: "GET",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);
```

#### Response `200` — Login history retrieved successfully

```json
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": [
  {
    "id": "507f1f77bcf86cd799439011",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "action": "auth.login",
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "success": true,
    "metadata": {}
  }
]
}
```

#### Response `401` — Unauthorized - Invalid or missing authentication

```json
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
```

#### Response `403` — Forbidden - Insufficient permissions

```json
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
```