Initial commit: Open sourcing all of the Maple Open Technologies code.

2025-12-02 14:33:08 -05:00 · 2025-12-02 14:33:08 -05:00 · 755d54a99d
commit 755d54a99d
2010 changed files with 448675 additions and 0 deletions
--- a/cloud/maplepress-backend/docs/API/login.md
+++ b/cloud/maplepress-backend/docs/API/login.md
@ -0,0 +1,99 @@
+# Login
+
+**POST /api/v1/login**
+
+Authenticate an existing user and obtain authentication tokens. This endpoint validates user credentials and creates a new session.
+
+**Authentication**: None required (public endpoint)
+
+**Headers**:
+- `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**:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "john@example.com",
+    "password": "SecurePassword123!"
+  }'
+```
+
+**Example Response** (200 OK):
+
+```json
+{
+  "user_id": "550e8400-e29b-41d4-a716-446655440000",
+  "user_email": "john@example.com",
+  "user_name": "John Doe",
+  "user_role": "user",
+  "tenant_id": "650e8400-e29b-41d4-a716-446655440000",
+  "session_id": "750e8400-e29b-41d4-a716-446655440000",
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "access_expiry": "2024-10-24T12:15:00Z",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_expiry": "2024-10-31T00:00:00Z",
+  "login_at": "2024-10-24T00:00:00Z"
+}
+```
+
+**Error Responses**:
+
+This endpoint returns errors in **RFC 9457 (Problem Details for HTTP APIs)** format.
+
+**Content-Type**: `application/problem+json`
+
+**400 Bad Request** - Invalid input:
+```json
+{
+  "type": "about:blank",
+  "title": "Bad Request",
+  "status": 400,
+  "detail": "Invalid request body format. Please check your JSON syntax."
+}
+```
+
+**401 Unauthorized** - Invalid credentials:
+```json
+{
+  "type": "about:blank",
+  "title": "Unauthorized",
+  "status": 401,
+  "detail": "Invalid email or password."
+}
+```
+
+**429 Too Many Requests** - Rate limit exceeded:
+```json
+{
+  "type": "about:blank",
+  "title": "Too Many Requests",
+  "status": 429,
+  "detail": "Too many login attempts from this IP address. Please try again later."
+}
+```
+
+**500 Internal Server Error**:
+```json
+{
+  "type": "about:blank",
+  "title": "Internal Server Error",
+  "status": 500,
+  "detail": "Failed to process login. Please try again later."
+}
+```
+
+**Notes**:
+- The `tenant_id` is required for multi-tenant authentication to ensure user credentials are validated within the correct tenant context
+- Access tokens expire after 15 minutes
+- Refresh tokens expire after 7 days
+- Both tokens are JWT tokens that should be stored securely on the client side
+- Use the access token in the `Authorization: JWT {token}` header for authenticated requests