Skip to content

authentication.md

Latest commit

 

History

History
38 lines (29 loc) · 2.51 KB

authentication.md

File metadata and controls

38 lines (29 loc) · 2.51 KB

Authentication

This API uses JSON Web Tokens (JWT) for securing endpoints. It employs a two-token strategy: an Access Token and a Refresh Token.

Access Token

  • Usage: Required for accessing protected API endpoints.
  • Format: Standard JWT.
  • Transmission: Must be included in the Authorization header of your request using the Bearer scheme.
  Authorization: Bearer <your_access_token>
  • Lifetime: Access tokens have a predefined expiration time (configured on the server, e.g., 15 minutes). Once expired, you'll receive a 401 Unauthorized error.
  • Obtaining: Received upon successful registration (/auth/register) or login (/auth/login). Can be renewed using a valid Refresh Token (/auth/refresh-token).

Refresh Token

  • Usage: Used to obtain a new Access Token when the current one expires, without requiring the user to log in again.
  • Format: Standard JWT.
  • Transmission: Automatically handled via an HttpOnly, Secure (in production), SameSite=Strict cookie named refreshToken. You generally don't need to manage this token directly in your client-side code.
  • Lifetime: Refresh tokens have a longer expiration time (configured on the server, e.g., 7 days).
  • Obtaining: Set automatically as a cookie upon successful registration or login.
  • Invalidation: Deleted from the server and the cookie is cleared upon logout (/auth/logout).

Authentication Flow

  1. Register or Login: Call /auth/register or /auth/login with valid credentials.
    • Receive an accessToken in the response body.
    • Receive a refreshToken set as an HttpOnly cookie.
  2. Access Protected Resources: Make requests to other API endpoints, including the accessToken in the Authorization: Bearer <token> header.
  3. Handle Expired Access Token: If a request returns a 401 Unauthorized error indicating an expired access token:
    • Call POST /auth/refresh-token. This endpoint uses the refreshToken cookie automatically sent by the browser.
    • Receive a new accessToken in the response.
    • Retry the original request with the new accessToken.
  4. Handle Expired Refresh Token: If the /auth/refresh-token endpoint returns a 401 Unauthorized error, the refresh token has expired or is invalid. The user must log in again via /auth/login.
  5. Logout: Call POST /auth/logout. This requires both the accessToken (in the header) and the refreshToken (in the cookie) to be valid. It invalidates the refresh token on the server and clears the cookie.