Authentication
This API uses cookie-based JSON Web Token (JWT) authentication to secure all protected endpoints. It employs a two-token system — an Access Token and a Refresh Token — both managed via HttpOnly cookies for enhanced security.
Access Token
Usage: Required to access protected routes within the API.
Storage: Sent to the client and stored as an
HttpOnly
cookie namedaccessToken
.Transmission: Automatically included in every request by the browser (no manual header handling required if cookies are enabled).
Format: Standard JWT.
Lifetime: Short-lived (e.g., 15 minutes). Once expired, requests to protected routes will return
401 Unauthorized
.Obtaining: Issued upon successful registration (
/auth/register
) or login (/auth/login
).Renewal: Automatically renewed using the Refresh Token through the
/auth/refresh-token
endpoint.
Refresh Token
Usage: Used to generate a new Access Token when it expires.
Storage: Sent to the client as an
HttpOnly
,Secure
(in production),SameSite=Strict
cookie namedrefreshToken
.Transmission: Automatically included in the request by the browser when calling
/auth/refresh-token
.Format: Standard JWT.
Lifetime: Longer-lived (e.g., 7 days).
Obtaining: Set as a cookie upon successful registration or login.
Invalidation: Deleted on the server and cleared from cookies upon logout (
/auth/logout
).
Authentication Flow
Register or Login
Call
POST /auth/register
orPOST /auth/login
with valid credentials.On success:
accessToken
andrefreshToken
are set as HttpOnly cookies.You can now access protected routes without manually managing tokens.
Access Protected Endpoints
Simply make API requests — cookies are automatically sent with requests.
If the
accessToken
is valid, the request succeeds.
Access Token Expired
When the
accessToken
expires, requests return401 Unauthorized
.Call
POST /auth/refresh-token
.The browser automatically sends the
refreshToken
cookie.A new
accessToken
(and optionally a newrefreshToken
) is issued and stored in cookies.
Retry your original request.
Refresh Token Expired or Invalid
If
/auth/refresh-token
returns401 Unauthorized
, the session has expired.The user must log in again via
/auth/login
.
Logout
Call
POST /auth/logout
.Both
accessToken
andrefreshToken
cookies are cleared on the client and invalidated on the server, ending the session.
Last updated