Docs.md

# Authentication System API Documentation

## Base URL
```
/v1/api
```

## Authentication Routes

### 1. Sign Up
Creates a new user account.

**Endpoint:** `POST /auth/signup`

**Request Body:**
```json
{
  "username": "string",
  "password": "string",
  "email": "string (optional)"
}
```

**Response (201 Created):**
```json
{
  "message": "User created successfully"
}
```

**Possible Errors:**
- `400 Bad Request`: Username already exists

### 2. Login
Authenticates a user and creates a new session.

**Endpoint:** `POST /auth/login`

**Headers:**
- `user-agent`: Browser/device user agent string (required)

**Request Body:**
```json
{
  "username": "string",
  "password": "string"
}
```

**Response (200 OK):**
```json
{
  "user_id": "string",
  "username": "string",
  "email": "string",
  "access_level": "string",
  "date_joined": "datetime",
  "access_token": "string",
  "token_type": "bearer"
}
```

**Possible Errors:**
- `401 Unauthorized`: Invalid credentials

### 3. Logout
Terminates an active session.

**Endpoint:** `POST /auth/logout`

**Query Parameters:**
- `user_id`: string
- `token`: string

**Response (200 OK):**
```json
{
  "message": "Session forcefully expired"
}
```

**Possible Errors:**
- `400 Bad Request`: No active sessions

### 4. Validate Token
Validates an existing session token.

**Endpoint:** `GET /auth/validate`

**Headers:**
- `user-agent`: Browser/device user agent string (required)

**Query Parameters:**
- `user_id`: string
- `token`: string

**Response (200 OK):**
```json
{
  "access_token": "string",
  "token_type": "bearer"
}
```

**Possible Errors:**
- `401 Unauthorized`: No active sessions, Device mismatch, Token expired, Invalid token

### 5. Search Users
Search for users by username.

**Endpoint:** `GET /auth/search-users`

**Query Parameters:**
- `query`: string

**Response (200 OK):**
```json
[
  "string"
]
```

### 6. Get User ID
Retrieve user ID by username.

**Endpoint:** `GET /auth/get-user-id`

**Query Parameters:**
- `username`: string

**Response (200 OK):**
```
"string" (user_id)
```

**Possible Errors:**
- `404 Not Found`: Username not found

### 7. Update Own Data
Update authenticated user's information.

**Endpoint:** `PUT /auth/user/update`

**Headers:**
- `token`: string
- `user-agent`: Browser/device user agent string (required)

**Query Parameters:**
- `user_id`: string

**Request Body:**
```json
{
  "password": "string (optional)",
  "email": "string (optional)",
  "username": "string (optional)"
}
```

**Response (200 OK):**
```json
{
  "username": "string",
  "email": "string",
  "access_level": "string",
  "date_joined": "datetime"
}
```

## Admin Routes

### 1. Get All Users
Retrieve all users (requires HUSH access level).

**Endpoint:** `GET /admin/users`

**Headers:**
- `user-agent`: Browser/device user agent string (required)

**Query Parameters:**
- `user_id`: string (admin's user ID)
- `token`: string

**Response (200 OK):**
```json
[
  {
    "username": "string",
    "email": "string",
    "access_level": "string",
    "date_joined": "datetime"
  }
]
```

**Possible Errors:**
- `403 Forbidden`: Insufficient permissions

### 2. Get User Details
Retrieve specific user details (requires HUSH access level).

**Endpoint:** `GET /admin/user/{user_id}`

**Headers:**
- `user-agent`: Browser/device user agent string (required)

**Query Parameters:**
- `admin_id`: string
- `token`: string

**Response (200 OK):**
```json
{
  "username": "string",
  "email": "string",
  "access_level": "string",
  "date_joined": "datetime"
}
```

### 3. Update User
Update user information (requires HUSH access level).

**Endpoint:** `PUT /admin/user/{user_id}`

**Headers:**
- `user-agent`: Browser/device user agent string (required)

**Query Parameters:**
- `admin_id`: string
- `token`: string

**Request Body:**
```json
{
  "password": "string (optional)",
  "email": "string (optional)",
  "username": "string (optional)"
}
```

### 4. Update Access Level
Update user access level (requires HUSH access level).

**Endpoint:** `PUT /admin/user/{user_id}/access-level`

**Headers:**
- `user-agent`: Browser/device user agent string (required)

**Query Parameters:**
- `admin_id`: string
- `token`: string

**Request Body:**
```json
{
  "access_level": "string"
}
```

## Access Levels
The system supports the following access levels in ascending order of privileges:
1. `default`
2. `member`
3. `admin`
4. `dev`
5. `hush`

## Notes
- All timestamps are in UTC
- Token expiration is set to 60 minutes
- Sessions are device-specific and validated against the user agent
- Database changes are saved to disk in debug mode
- The system automatically creates a HUSH-level system user on startup