Authentication API

All auth endpoints are prefixed with /api/auth.

Schemas

UserCreate

Request body for user registration.

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.

Field	Type	Required	Notes
email	string	Yes
password	string	Yes

TokenResponse

Returned by login, signup, and OAuth endpoints.

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

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.

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

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

{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "...",
  "user": { ... }
}

Error responses

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

POST /api/auth/login HTTP/1.1
Content-Type: application/json

{
  "email": "jane@example.com",
  "password": "securepass"
}

Response 200 OK — TokenResponse

Error responses

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

POST /api/auth/google/url HTTP/1.1
Content-Type: application/json

{
  "redirect_uri": "https://yourdomain.com/auth/callback"
}

Response 200 OK

{
  "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

POST /api/auth/google/callback HTTP/1.1
Content-Type: application/json

{
  "code": "<oauth_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

POST /api/auth/google/token HTTP/1.1
Content-Type: application/json

{
  "id_token": "<google_id_token>"
}

Response 200 OK — TokenResponse

---

POST /api/auth/refresh

Exchange a refresh token for a new access token.

Request

POST /api/auth/refresh HTTP/1.1
Content-Type: application/json

{
  "refresh_token": "<refresh_token>"
}

Response 200 OK — TokenResponse

Error responses

Status	Detail
401	Token expired or invalid

---

POST /api/auth/logout

Invalidate the current session.

Request

POST /api/auth/logout HTTP/1.1
Authorization: Bearer <access_token>

Response 200 OK

{
  "message": "Logged out successfully",
  "success": true
}

---

GET /api/auth/me

Return the currently authenticated user’s profile.

Request

GET /api/auth/me HTTP/1.1
Authorization: Bearer <access_token>

Response 200 OK — UserResponse

Error responses

Status	Detail
401	Missing or invalid token

---

PUT /api/auth/onboarding

Update learning preferences collected during onboarding. Requires authentication.

Request

PUT /api/auth/onboarding HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "proficiency_level": "Intermediate",
  "goals": ["Business & Work", "Education"],
  "focus_areas": ["Speaking", "Grammar"]
}

Response 200 OK

{
  "message": "Onboarding updated successfully",
  "success": true
}

Error responses

Status	Detail
401	Missing or invalid token
400	Profile update failed

---

Summary Table

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)