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/register.md
+++ b/cloud/maplepress-backend/docs/API/register.md
@ -0,0 +1,149 @@
+# Register User & Tenant
+
+**POST /api/v1/register**
+
+Register a new user and create a new tenant (organization) in a single request. This is the primary onboarding endpoint that returns authentication tokens.
+
+**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 (min 8 characters) |
+| confirm_password | string | Yes | Password confirmation (must match password) |
+| first_name | string | Yes | User's first name |
+| last_name | string | Yes | User's last name |
+| tenant_name | string | Yes | Organization/tenant name (slug auto-generated from this) |
+| timezone | string | No | User's timezone (e.g., "America/New_York", defaults to "UTC" if not provided) |
+| agree_terms_of_service | boolean | Yes | Must be true - user agreement to Terms of Service |
+| agree_promotions | boolean | No | Optional - user agreement to receive promotional emails (default: false) |
+| agree_to_tracking_across_third_party_apps_and_services | boolean | No | Optional - user agreement to cross-platform tracking (default: false) |
+
+**Example Request (with timezone)**:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "john@example.com",
+    "password": "SecurePassword123!",
+    "confirm_password": "SecurePassword123!",
+    "first_name": "John",
+    "last_name": "Doe",
+    "tenant_name": "Acme Corporation",
+    "timezone": "America/New_York",
+    "agree_terms_of_service": true,
+    "agree_promotions": false,
+    "agree_to_tracking_across_third_party_apps_and_services": false
+  }'
+```
+
+**Example Request (without timezone - defaults to UTC)**:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "jane@example.com",
+    "password": "SecurePassword456!",
+    "confirm_password": "SecurePassword456!",
+    "first_name": "Jane",
+    "last_name": "Smith",
+    "tenant_name": "Beta Inc",
+    "agree_terms_of_service": true
+  }'
+```
+
+**Example Response** (201 Created):
+
+```json
+{
+  "user_id": "550e8400-e29b-41d4-a716-446655440000",
+  "user_email": "john@example.com",
+  "user_name": "John Doe",
+  "user_role": "manager",
+  "tenant_id": "650e8400-e29b-41d4-a716-446655440000",
+  "tenant_name": "Acme Corporation",
+  "tenant_slug": "acme-corp",
+  "session_id": "750e8400-e29b-41d4-a716-446655440000",
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "access_expiry": "2024-10-24T12:00:00Z",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_expiry": "2024-11-24T00:00:00Z",
+  "created_at": "2024-10-24T00:00:00Z"
+}
+```
+
+**Error Responses**:
+
+This endpoint returns errors in **RFC 9457 (Problem Details for HTTP APIs)** format.
+
+**Validation Error Response** (400 Bad Request):
+
+```json
+{
+  "type": "about:blank",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "One or more validation errors occurred",
+  "errors": {
+    "email": ["Invalid email format"],
+    "password": ["Field is required", "Password must be at least 8 characters"],
+    "confirm_password": ["Field is required", "Passwords do not match"],
+    "first_name": ["Field is required"],
+    "last_name": ["Field is required"],
+    "tenant_name": ["Field is required"],
+    "agree_terms_of_service": ["Must agree to terms of service"]
+  }
+}
+```
+
+**Content-Type**: `application/problem+json`
+
+**Common Validation Error Messages**:
+
+| Field | Error Messages |
+|-------|---------------|
+| email | "Invalid email format", "Field is required" |
+| password | "Field is required", "Password must be at least 8 characters", "Password must contain at least one uppercase letter (A-Z)", "Password must contain at least one lowercase letter (a-z)", "Password must contain at least one number (0-9)", "Password must contain at least one special character" |
+| confirm_password | "Field is required", "Passwords do not match" |
+| first_name | "Field is required", "First_name must be between 1 and 100 characters" |
+| last_name | "Field is required", "Last_name must be between 1 and 100 characters" |
+| tenant_name | "Field is required", "Tenant_name must be between 1 and 100 characters" |
+| agree_terms_of_service | "Must agree to terms of service" |
+
+**Other Error Responses**:
+
+- `409 Conflict`: Email or tenant slug already exists
+  ```json
+  {
+    "type": "about:blank",
+    "title": "Conflict",
+    "status": 409,
+    "detail": "Registration failed. The provided information is already in use"
+  }
+  ```
+
+- `500 Internal Server Error`: Server error
+  ```json
+  {
+    "type": "about:blank",
+    "title": "Internal Server Error",
+    "status": 500,
+    "detail": "Failed to register user"
+  }
+  ```
+
+**Important Notes**:
+- `agree_terms_of_service` must be `true` or the request will fail with 400 Bad Request
+- `first_name` and `last_name` are required fields
+- `timezone` is optional and defaults to "UTC" if not provided
+- Password must be at least 8 characters long
+- **Tenant slug is automatically generated** from `tenant_name` (converted to lowercase, special chars replaced with hyphens)
+- The IP address of the request is automatically captured for audit trail purposes
+- User role for registration is always "manager" (tenant creator)