Authentication

Authentication Flow

1. User registers or logs in
2. Server issues an access token and a refresh token
3. Client uses the access token for authenticated requests
4. When the access token expires, the client uses the refresh token to obtain a new access token
5. If the refresh token is invalid or expired, the user must log in again

Endpoints

1. Register

Click to view/hide register flow diagram

• URL: /auth/register
• Method: POST
• Request Body: Requires username, email, and password
• Response: User object
• Description: Creates a new user account. The username and email must be unique.

2. Login

Click to view/hide login flow diagram

• URL: /auth/login
• Method: POST
• Request Body: Requires username and password
• Response: Returns access_token, refresh_token, token_type, and expires_at
• Description: Authenticates a user and returns access and refresh tokens.

3. Refresh Token

Click to view/hide token refresh flow diagram

• URL: /auth/refresh
• Method: POST
• Request Body: Requires refresh_token
• Response: Same as login response
• Description: Uses a valid refresh token to obtain a new access token.

4. Logout

Click to view/hide logout flow diagram

• URL: /auth/logout
• Method: POST
• Headers: Authorization: Bearer {access_token}
• Response: Message confirming logout
• Description: Invalidates the current access token, effectively logging out the user.

Token Usage

• Include the access token in the Authorization header for authenticated requests
• The access token is typically valid for a short period (e.g., 15 minutes)
• Use the refresh token to obtain a new access token when it expires
• Store tokens securely on the client side (e.g., in secure HTTP-only cookies or encrypted local storage)

Implementation Details

• Passwords are hashed using bcrypt before storage
• Tokens are JWT (JSON Web Tokens) signed with a secret key
• Refresh tokens are stored in the database and validated on each use
• Failed login attempts are logged and may trigger account lockouts (implement if not already in place)