Enhance Authentication API documentation with detailed endpoints and error responses
This commit is contained in:
Isuru Bimsara
+177
-39
@@ -1,23 +1,48 @@
|
||||
# Auth API
|
||||
# Authentication API
|
||||
|
||||
#### Request OTP
|
||||
The Authentication API provides OTP-based login, access-token renewal, password recovery, current-user lookup, and logout.
|
||||
|
||||
**Endpoint**
|
||||
## Base URL
|
||||
|
||||
```
|
||||
POST: http://localhost:3070/api/auth/req-otp
|
||||
```text
|
||||
http://localhost:3070/api/auth
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
Requests and responses use JSON unless otherwise stated.
|
||||
|
||||
## Authentication
|
||||
|
||||
After a successful login, the API returns an access token in the response and sets two HTTP-only cookies:
|
||||
|
||||
- `access_token` — valid for 15 minutes
|
||||
- `refresh_token` — valid for 7 days
|
||||
|
||||
Protected endpoints accept the access token through the `access_token` cookie or this header:
|
||||
|
||||
```http
|
||||
Authorization: Bearer <access-token>
|
||||
```
|
||||
|
||||
When using cookie authentication from a browser, send requests with credentials enabled.
|
||||
|
||||
---
|
||||
|
||||
## Request OTP
|
||||
|
||||
Validates the user's email and password, then sends a one-time password to the registered email address.
|
||||
|
||||
**Endpoint:** `POST` [http://localhost:3070/api/auth/req-otp](http://localhost:3070/api/auth/req-otp)
|
||||
|
||||
### Request body
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "sathira@niolla.lk",
|
||||
"email": "sathira@niolla.lk",
|
||||
"password": "Niolla@123"
|
||||
}
|
||||
```
|
||||
|
||||
**Respond**
|
||||
### Success response — `201 Created`
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -26,26 +51,30 @@ POST: http://localhost:3070/api/auth/req-otp
|
||||
}
|
||||
```
|
||||
|
||||
### Error responses
|
||||
|
||||
- `401 Unauthorized` — invalid password
|
||||
- `404 Not Found` — user not found
|
||||
- `500 Internal Server Error` — OTP generation or email delivery failed
|
||||
|
||||
---
|
||||
|
||||
#### Login
|
||||
## Login
|
||||
|
||||
**Endpoint**
|
||||
Verifies the emailed OTP and creates an authenticated session. The user account must be active.
|
||||
|
||||
```
|
||||
POST: http://localhost:3070/api/auth/login
|
||||
```
|
||||
**Endpoint:** `POST` [http://localhost:3070/api/auth/login](http://localhost:3070/api/auth/login)
|
||||
|
||||
**Request Body**
|
||||
### Request body
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "sathira@niolla.lk",
|
||||
"email": "sathira@niolla.lk",
|
||||
"otp": "922304"
|
||||
}
|
||||
```
|
||||
|
||||
**Respond**
|
||||
### Success response — `200 OK`
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -54,33 +83,40 @@ POST: http://localhost:3070/api/auth/login
|
||||
"data": {
|
||||
"id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
|
||||
"email": "sathira@niolla.lk",
|
||||
"firstName": "Jhon",
|
||||
"lastName": "Doe",
|
||||
"firstName": "Sathira",
|
||||
"lastName": "Sri Sathsara",
|
||||
"role": null,
|
||||
"accountType": "admin",
|
||||
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9......"
|
||||
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The response also sets the `access_token` and `refresh_token` HTTP-only cookies.
|
||||
|
||||
### Error responses
|
||||
|
||||
- `400 Bad Request` — email or OTP is missing
|
||||
- `401 Unauthorized` — OTP is invalid or expired
|
||||
- `403 Forbidden` — account is not active
|
||||
- `404 Not Found` — user not found
|
||||
- `500 Internal Server Error` — login failed unexpectedly
|
||||
|
||||
---
|
||||
|
||||
#### Get Current User
|
||||
## Get Current User
|
||||
|
||||
**Endpoint**
|
||||
Returns the authenticated user's token claims and effective permissions.
|
||||
|
||||
```
|
||||
GET: http://localhost:3070/api/auth/me
|
||||
```
|
||||
**Endpoint:** `GET` [http://localhost:3070/api/auth/me](http://localhost:3070/api/auth/me)
|
||||
|
||||
**Authorization**: Required (Bearer token)
|
||||
**Authentication:** Required
|
||||
|
||||
**Request Body**
|
||||
### Request body
|
||||
|
||||
```
|
||||
No Body
|
||||
```
|
||||
No request body.
|
||||
|
||||
**Response (200)**
|
||||
### Success response — `200 OK`
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -98,27 +134,129 @@ No Body
|
||||
}
|
||||
```
|
||||
|
||||
### Error responses
|
||||
|
||||
- `401 Unauthorized` — token is missing, invalid, or expired
|
||||
|
||||
---
|
||||
|
||||
### Logout
|
||||
## Refresh Session
|
||||
|
||||
**Endpoint**
|
||||
Uses the HTTP-only refresh-token cookie to rotate the session and issue new access and refresh cookies.
|
||||
|
||||
```
|
||||
POST: http://localhost:3070/api/auth/logout
|
||||
**Endpoint:** `POST` [http://localhost:3070/api/auth/refresh](http://localhost:3070/api/auth/refresh)
|
||||
|
||||
### Request body
|
||||
|
||||
No request body. The `refresh_token` cookie is required.
|
||||
|
||||
### Success response — `200 OK`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Session refreshed successfully"
|
||||
}
|
||||
```
|
||||
|
||||
**Request Body**
|
||||
### Error response — `401 Unauthorized`
|
||||
|
||||
```
|
||||
No Body
|
||||
Returned when the refresh cookie is missing or the session is invalid, expired, or no longer active.
|
||||
|
||||
---
|
||||
|
||||
## Forgot Password
|
||||
|
||||
Sends a password-reset link when an account exists for the supplied email. The same success response is returned for unknown email addresses to prevent account discovery.
|
||||
|
||||
**Endpoint:** `POST` [http://localhost:3070/api/auth/forgot-password](http://localhost:3070/api/auth/forgot-password)
|
||||
|
||||
**Authentication:** Not required
|
||||
|
||||
### Request body
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "sathira@niolla.lk"
|
||||
}
|
||||
```
|
||||
|
||||
**Respond**
|
||||
### Success response — `200 OK`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "If an account exists for this email, a password reset link has been sent."
|
||||
}
|
||||
```
|
||||
|
||||
### Error responses
|
||||
|
||||
- `400 Bad Request` — email is missing or invalid
|
||||
- `500 Internal Server Error` — the reset request could not be processed
|
||||
|
||||
---
|
||||
|
||||
## Reset Password
|
||||
|
||||
Sets a new password using the token from the password-reset email. A successful reset invalidates all existing refresh sessions for the user.
|
||||
|
||||
**Endpoint:** `POST` [http://localhost:3070/api/auth/reset-password](http://localhost:3070/api/auth/reset-password)
|
||||
|
||||
**Authentication:** Not required
|
||||
|
||||
### Request body
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "password-reset-token",
|
||||
"newPassword": "NewPassword@1234",
|
||||
"confirmPassword": "NewPassword@1234"
|
||||
}
|
||||
```
|
||||
|
||||
The new password must contain at least one uppercase letter, one lowercase letter, one symbol, and four digits. It must differ from the current password.
|
||||
|
||||
### Success response — `200 OK`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Password reset successfully. Please login again."
|
||||
}
|
||||
```
|
||||
|
||||
### Error responses
|
||||
|
||||
- `400 Bad Request` — fields are missing, passwords do not match, password rules are not met, the new password matches the current password, or the token is invalid or expired
|
||||
- `500 Internal Server Error` — password reset failed unexpectedly
|
||||
|
||||
---
|
||||
|
||||
## Logout
|
||||
|
||||
Deletes the current refresh session when available and clears both authentication cookies.
|
||||
|
||||
**Endpoint:** `POST` [http://localhost:3070/api/auth/logout](http://localhost:3070/api/auth/logout)
|
||||
|
||||
### Request body
|
||||
|
||||
No request body.
|
||||
|
||||
### Success response — `200 OK`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Logged out successfully"
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### Error response — `500 Internal Server Error`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Failed to logout"
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user