API Reference

Full interactive API documentation with request/response schemas is available at /api/doc (Swagger UI) when running the backend locally.

Base URL

Environment	URL
Local	`http://localhost`
Production	`https://yourdomain.com`

All endpoints are prefixed with /api/v1/.

Protected endpoints require a JWT bearer token:

Authorization: Bearer eyJ...

Tokens are obtained from login, register, social login, or token refresh endpoints. Access tokens expire after 1 hour.

#	Method	Path	Auth	Description
1	POST	`/api/v1/auth/register`	Public	Register a new user
2	POST	`/api/v1/auth/login`	Public	Login with email/password
3	POST	`/api/v1/auth/social`	Public	Login/register with Firebase token
4	POST	`/api/v1/auth/token/refresh`	Public	Refresh JWT using refresh token
5	POST	`/api/v1/auth/logout`	JWT	Logout and invalidate refresh tokens
6	GET	`/api/v1/auth/validate-email/{token}`	Public	Validate email (redirects)
7	POST	`/api/v1/auth/forgot-password`	Public	Request password reset email
8	GET	`/api/v1/auth/reset-password/{token}`	Public	Reset password redirect
9	POST	`/api/v1/auth/reset-password`	Public	Submit new password with reset token
10	GET	`/api/v1/user/profile`	JWT	Get current user profile
11	POST	`/api/v1/user/change-password`	JWT	Change password
12	GET	`/api/v1/plans`	Public	List available subscription plans
13	POST	`/api/v1/subscription/checkout`	Optional	Create Stripe checkout session
14	GET	`/api/v1/subscription`	JWT	Get current subscription status
15	POST	`/api/v1/webhooks/stripe`	Stripe	Stripe webhook receiver
16	GET	`/api/doc`	Public	OpenAPI / Swagger UI

Auth legend:

Public — no authentication required
JWT — requires Authorization: Bearer <token> header
Optional — works with or without JWT (authenticated checkout pre-fills email)
Stripe — verified via Stripe-Signature header

Rate limiters are configured in config/packages/rate_limiter.yaml — see Configuration > Rate Limiting for details.

All errors follow a consistent format:

{
  "error": "Error type or message"
}

Some errors include additional details:

{
  "error": "Validation failed",
  "message": "Email is already in use"
}

Rate limit responses:

HTTP 429 Too Many Requests
{
  "error": "Too many requests. Please try again later."
}

Code	Meaning
200	Success
201	Created (registration, new social login)
202	Accepted (forgot password — always, to prevent enumeration)
400	Bad request (validation errors, missing fields)
401	Unauthorized (invalid credentials, expired JWT)
404	Not found (user, subscription, token)
429	Too many requests (rate limited)