diff --git a/docs/api/authentication/login.md b/docs/api/authentication/login.md new file mode 100644 index 0000000..644a5b2 --- /dev/null +++ b/docs/api/authentication/login.md @@ -0,0 +1,49 @@ +# Login User + +Authenticate with email and password. + +**Endpoint**: `POST /api/auth/login` +**Auth**: Not required +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| email | string | Yes | User's email address | +| password | string | Yes | User's password | + +### Example Request + +```json +{ + "email": "user@example.com", + "password": "SecureP@ss123!" +} +``` + +## Response (200 OK) + +```json +{ + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refresh_token": "d4f5g6h7...", + "user": { + "id": "uuid-here", + "email": "user@example.com", + "username": "john", + "role": "user" + } +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid email or password | +| 400 | Missing required fields | + +## Try It Out + + diff --git a/docs/api/authentication/logout.md b/docs/api/authentication/logout.md new file mode 100644 index 0000000..9b2c969 --- /dev/null +++ b/docs/api/authentication/logout.md @@ -0,0 +1,35 @@ +# Logout User + +Invalidate the current JWT token. + +**Endpoint**: `POST /api/auth/logout` +**Auth**: Required +**Content-Type**: `application/json` + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token (e.g., `Bearer eyJhbG...`) | + +### Example Request + +```http +POST /api/auth/logout +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (204 No Content) + +No response body. + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | +| 403 | Token already invalidated | + +## Try It Out + + diff --git a/docs/api/authentication/refresh_token.md b/docs/api/authentication/refresh_token.md new file mode 100644 index 0000000..8906ddf --- /dev/null +++ b/docs/api/authentication/refresh_token.md @@ -0,0 +1,41 @@ +# Refresh Token + +Obtain a new JWT token using a refresh token. + +**Endpoint**: `POST /api/auth/refresh` +**Auth**: Not required (uses refresh token) +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| refresh_token | string | Yes | Valid refresh token | + +### Example Request + +```json +{ + "refresh_token": "d4f5g6h7..." +} +``` + +## Response (200 OK) + +```json +{ + "token": "new-jwt-token", + "refresh_token": "new-refresh-token" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired refresh token | +| 400 | Missing refresh token | + +## Try It Out + + diff --git a/docs/api/authentication/register.md b/docs/api/authentication/register.md new file mode 100644 index 0000000..34b978e --- /dev/null +++ b/docs/api/authentication/register.md @@ -0,0 +1,57 @@ +# Register User + +Create a new user account. + +**Endpoint**: `POST /api/auth/register` +**Auth**: Not required +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| email | string | Yes | User's email address | +| username | string | Yes | Desired username | +| password | string | Yes | Password (min 8 chars) | +| first_name | string | No | User's first name | +| last_name | string | No | User's last name | + +### Example Request + +```json +{ + "email": "user@example.com", + "username": "john", + "password": "SecureP@ss123!", + "first_name": "John", + "last_name": "Doe" +} +``` + +## Response (201 Created) + +```json +{ + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "refresh_token": "d4f5g6h7...", + "user": { + "id": "uuid-here", + "email": "user@example.com", + "username": "john", + "role": "user", + "theme": "tokyo-night", + "created_at": "2026-01-31T10:00:00Z" + } +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid email format, weak password, or missing fields | +| 409 | Email or username already exists | + +## Try It Out + + diff --git a/docs/api/users/change_password.md b/docs/api/users/change_password.md new file mode 100644 index 0000000..43b2965 --- /dev/null +++ b/docs/api/users/change_password.md @@ -0,0 +1,39 @@ +# Change Password + +Change the current user's password. + +**Endpoint**: `PUT /api/users/me/password` +**Auth**: Required +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| current_password | string | Yes | Current password | +| new_password | string | Yes | New password (min 8 chars) | + +### Example Request + +```json +{ + "current_password": "oldPassword", + "new_password": "NewSecureP@ss123!" +} +``` + +## Response (204 No Content) + +Password changed successfully. + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid input or weak password | +| 401 | Current password is incorrect | +| 401 | Invalid or expired token | + +## Try It Out + + diff --git a/docs/api/users/get_profile.md b/docs/api/users/get_profile.md new file mode 100644 index 0000000..6cdfcac --- /dev/null +++ b/docs/api/users/get_profile.md @@ -0,0 +1,45 @@ +# Get Current User Profile + +Retrieve the current authenticated user's profile. + +**Endpoint**: `GET /api/users/me` +**Auth**: Required + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token | + +### Example Request + +```http +GET /api/users/me +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "id": "uuid", + "email": "user@example.com", + "username": "john", + "first_name": "John", + "last_name": "Doe", + "theme": "tokyo-night", + "role": "user", + "max_devices": 10, + "created_at": "2026-01-31T10:00:00Z" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 401 | Invalid or expired token | + +## Try It Out + + diff --git a/docs/api/users/update_profile.md b/docs/api/users/update_profile.md new file mode 100644 index 0000000..0b6a616 --- /dev/null +++ b/docs/api/users/update_profile.md @@ -0,0 +1,50 @@ +# Update Profile + +Update the current user's profile information. + +**Endpoint**: `PUT /api/users/me/profile` +**Auth**: Required +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| first_name | string | No | User's first name | +| last_name | string | No | User's last name | + +### Example Request + +```json +{ + "first_name": "John", + "last_name": "Smith" +} +``` + +## Response (200 OK) + +```json +{ + "id": "uuid", + "email": "user@example.com", + "username": "john", + "first_name": "John", + "last_name": "Smith", + "theme": "tokyo-night", + "role": "user", + "max_devices": 10, + "created_at": "2026-01-31T10:00:00Z" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid input data | +| 401 | Invalid or expired token | + +## Try It Out + + diff --git a/docs/api/users/update_theme.md b/docs/api/users/update_theme.md new file mode 100644 index 0000000..1cf1d96 --- /dev/null +++ b/docs/api/users/update_theme.md @@ -0,0 +1,44 @@ +# Update Theme + +Update the current user's theme preference. + +**Endpoint**: `PUT /api/users/me/theme` +**Auth**: Required +**Content-Type**: `application/json` + +## Request Body + +| Field | Type | Required | Description | +|--------|------|-----------|-------------| +| theme | string | Yes | Theme name (e.g., "tokyo-night", "dracula") | + +### Example Request + +```json +{ + "theme": "dracula" +} +``` + +## Response (200 OK) + +```json +{ + "id": "uuid", + "email": "user@example.com", + "username": "john", + "theme": "dracula", + "role": "user" +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Invalid theme name | +| 401 | Invalid or expired token | + +## Try It Out + +