.. _api-auth: Authentication API ================== All auth endpoints are prefixed with ``/api/auth``. Schemas ------- UserCreate ~~~~~~~~~~ Request body for user registration. .. list-table:: :header-rows: 1 :widths: 22 15 15 48 * - Field - Type - Required - Notes * - ``email`` - string - Yes - Valid email address * - ``password`` - string - Yes - Minimum 8 characters * - ``full_name`` - string - Yes - 2 – 100 characters * - ``proficiency_level`` - ProficiencyLevel - No - Default: ``Beginner`` * - ``goals`` - GoalEnum[] - No - Array; default ``[]`` * - ``focus_areas`` - FocusAreaEnum[] - No - Array; default ``[]`` UserLogin ~~~~~~~~~ Request body for email/password login. .. list-table:: :header-rows: 1 :widths: 22 15 15 48 * - Field - Type - Required - Notes * - ``email`` - string - Yes - * - ``password`` - string - Yes - TokenResponse ~~~~~~~~~~~~~ Returned by login, signup, and OAuth endpoints. .. list-table:: :header-rows: 1 :widths: 22 15 63 * - Field - Type - Notes * - ``access_token`` - string - JWT; expires in 24 h * - ``token_type`` - string - Always ``"bearer"`` * - ``expires_in`` - integer - Seconds until expiry (86400) * - ``refresh_token`` - string - Used with ``/api/auth/refresh`` * - ``user`` - UserResponse - Current user object UserResponse ~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 22 15 63 * - Field - Type - Notes * - ``id`` - string (UUID) - * - ``email`` - string - * - ``full_name`` - string - * - ``avatar_url`` - string \| null - * - ``provider`` - string - ``"email"`` or ``"google"`` * - ``proficiency_level`` - ProficiencyLevel \| null - * - ``goals`` - GoalEnum[] - * - ``focus_areas`` - FocusAreaEnum[] - * - ``created_at`` - string (ISO 8601) - OnboardingUpdate ~~~~~~~~~~~~~~~~ Request body for updating learning preferences. .. list-table:: :header-rows: 1 :widths: 22 15 15 48 * - Field - Type - Required - Notes * - ``proficiency_level`` - ProficiencyLevel - No - * - ``goals`` - GoalEnum[] - No - * - ``focus_areas`` - FocusAreaEnum[] - No - Enumerations ~~~~~~~~~~~~ **ProficiencyLevel** ``Beginner`` | ``Elementary`` | ``Intermediate`` | ``Advanced`` | ``Fluent`` **GoalEnum** ``Travel & Tourism`` | ``Business & Work`` | ``Education`` | ``Daily Conversation`` | ``Culture & Entertainment`` | ``Family & Friends`` **FocusAreaEnum** ``Speaking`` | ``Listening`` | ``Reading`` | ``Writing`` | ``Vocabulary`` | ``Grammar`` ---- Endpoints --------- POST /api/auth/signup ~~~~~~~~~~~~~~~~~~~~~ Register a new user with email and password. **Request** .. code-block:: http POST /api/auth/signup HTTP/1.1 Content-Type: application/json { "email": "jane@example.com", "password": "securepass", "full_name": "Jane Doe", "proficiency_level": "Intermediate", "goals": ["Education", "Daily Conversation"], "focus_areas": ["Reading", "Writing"] } **Response** ``201 Created`` .. code-block:: json { "access_token": "eyJhbGci...", "token_type": "bearer", "expires_in": 86400, "refresh_token": "...", "user": { ... } } **Error responses** .. list-table:: :header-rows: 1 :widths: 15 85 * - Status - Detail * - ``400`` - ``"User already registered"`` or other Supabase auth error * - ``422`` - Pydantic validation failure (e.g. password too short) ---- POST /api/auth/login ~~~~~~~~~~~~~~~~~~~~~ Authenticate with email and password. **Request** .. code-block:: http POST /api/auth/login HTTP/1.1 Content-Type: application/json { "email": "jane@example.com", "password": "securepass" } **Response** ``200 OK`` — ``TokenResponse`` **Error responses** .. list-table:: :header-rows: 1 :widths: 15 85 * - Status - Detail * - ``400`` - ``"Invalid email or password"`` * - ``401`` - Supabase session rejected ---- POST /api/auth/google/url ~~~~~~~~~~~~~~~~~~~~~~~~~ Obtain the Google OAuth authorisation URL to redirect the browser. **Request** .. code-block:: http POST /api/auth/google/url HTTP/1.1 Content-Type: application/json { "redirect_uri": "https://yourdomain.com/auth/callback" } **Response** ``200 OK`` .. code-block:: json { "url": "https://accounts.google.com/o/oauth2/v2/auth?..." } ---- POST /api/auth/google/callback ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Exchange the authorisation code returned by Google for a session. **Request** .. code-block:: http POST /api/auth/google/callback HTTP/1.1 Content-Type: application/json { "code": "" } **Response** ``200 OK`` — ``TokenResponse`` ---- POST /api/auth/google/token ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sign in using a Google ID token obtained by the native mobile SDK (``google_sign_in``). Use this for Android/iOS clients. **Request** .. code-block:: http POST /api/auth/google/token HTTP/1.1 Content-Type: application/json { "id_token": "" } **Response** ``200 OK`` — ``TokenResponse`` ---- POST /api/auth/refresh ~~~~~~~~~~~~~~~~~~~~~~ Exchange a refresh token for a new access token. **Request** .. code-block:: http POST /api/auth/refresh HTTP/1.1 Content-Type: application/json { "refresh_token": "" } **Response** ``200 OK`` — ``TokenResponse`` **Error responses** .. list-table:: :header-rows: 1 :widths: 15 85 * - Status - Detail * - ``401`` - Token expired or invalid ---- POST /api/auth/logout ~~~~~~~~~~~~~~~~~~~~~ Invalidate the current session. **Request** .. code-block:: http POST /api/auth/logout HTTP/1.1 Authorization: Bearer **Response** ``200 OK`` .. code-block:: json { "message": "Logged out successfully", "success": true } ---- GET /api/auth/me ~~~~~~~~~~~~~~~~ Return the currently authenticated user's profile. **Request** .. code-block:: http GET /api/auth/me HTTP/1.1 Authorization: Bearer **Response** ``200 OK`` — ``UserResponse`` **Error responses** .. list-table:: :header-rows: 1 :widths: 15 85 * - Status - Detail * - ``401`` - Missing or invalid token ---- PUT /api/auth/onboarding ~~~~~~~~~~~~~~~~~~~~~~~~ Update learning preferences collected during onboarding. Requires authentication. **Request** .. code-block:: http PUT /api/auth/onboarding HTTP/1.1 Authorization: Bearer Content-Type: application/json { "proficiency_level": "Intermediate", "goals": ["Business & Work", "Education"], "focus_areas": ["Speaking", "Grammar"] } **Response** ``200 OK`` .. code-block:: json { "message": "Onboarding updated successfully", "success": true } **Error responses** .. list-table:: :header-rows: 1 :widths: 15 85 * - Status - Detail * - ``401`` - Missing or invalid token * - ``400`` - Profile update failed ---- Summary Table ------------- .. list-table:: :header-rows: 1 :widths: 10 35 20 35 * - Method - Path - Auth required - Returns * - ``POST`` - ``/api/auth/signup`` - No - ``TokenResponse`` (201) * - ``POST`` - ``/api/auth/login`` - No - ``TokenResponse`` (200) * - ``POST`` - ``/api/auth/google/url`` - No - ``{ url }`` (200) * - ``POST`` - ``/api/auth/google/callback`` - No - ``TokenResponse`` (200) * - ``POST`` - ``/api/auth/google/token`` - No - ``TokenResponse`` (200) * - ``POST`` - ``/api/auth/refresh`` - No - ``TokenResponse`` (200) * - ``POST`` - ``/api/auth/logout`` - Yes - ``MessageResponse`` (200) * - ``GET`` - ``/api/auth/me`` - Yes - ``UserResponse`` (200) * - ``PUT`` - ``/api/auth/onboarding`` - Yes - ``MessageResponse`` (200)