API Reference

Complete list of backend API endpoints

API Reference

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

Base URL

EnvironmentURL
Localhttp://localhost
Productionhttps://yourdomain.com

All endpoints are prefixed with /api/v1/.

Authentication

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.

Endpoints

#MethodPathAuthDescription
1POST/api/v1/auth/registerPublicRegister a new user
2POST/api/v1/auth/loginPublicLogin with email/password
3POST/api/v1/auth/socialPublicLogin/register with Firebase token
4POST/api/v1/auth/token/refreshPublicRefresh JWT using refresh token
5POST/api/v1/auth/logoutJWTLogout and invalidate refresh tokens
6GET/api/v1/auth/validate-email/{token}PublicValidate email (redirects)
7POST/api/v1/auth/forgot-passwordPublicRequest password reset email
8GET/api/v1/auth/reset-password/{token}PublicReset password redirect
9POST/api/v1/auth/reset-passwordPublicSubmit new password with reset token
10GET/api/v1/user/profileJWTGet current user profile
11POST/api/v1/user/change-passwordJWTChange password
12GET/api/v1/plansPublicList available subscription plans
13POST/api/v1/subscription/checkoutOptionalCreate Stripe checkout session
14GET/api/v1/subscriptionJWTGet current subscription status
15POST/api/v1/webhooks/stripeStripeStripe webhook receiver

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 Limits

EndpointIP LimitEmail Limit
Register5 / 15 min3 / 15 min
Login5 / 15 min5 / 15 min
Social Login5 / 15 min—
Logout10 / 1 min—
Admin Login5 / 15 min—

Error Responses

All errors follow a consistent format:

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

Common Status Codes

CodeMeaning
200Success
201Created (registration, new social login)
202Accepted (forgot password)
400Bad request (validation errors, missing fields)
401Unauthorized (invalid credentials, expired JWT)
404Not found
429Too many requests (rate limited)
Previous ← CommunicationNextTesting →