API — Auth

Tóm tắt endpoint

Method	Path	Mô tả	Auth	Rate limit
POST	`/api/v1/auth/register`	Đăng ký user, trả token pair.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/login`	Đăng nhập bằng email/username + password.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/forgot-password`	Tạo reset token và enqueue email.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/profile`	Update profile. [CẦN XÁC NHẬN] service chỉ trả updated.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/refresh-token`	Rotate refresh token từ x-refresh-token.	x-refresh-token	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/auth/me`	Lấy user hiện tại, cache Redis 30s.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/logout`	Blacklist access token và revoke refresh token.	Bearer + x-refresh-token	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/resend-verify-email`	Gửi lại email verify.	Bearer	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/verify-email`	Verify email bằng token.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/validate/email`	Check Bloom filter email availability.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/validate/username`	Check Bloom filter username availability.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
GET	`/api/v1/auth/reset-password/validate`	Validate reset token. [CẦN XÁC NHẬN] luôn valid true.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.
POST	`/api/v1/auth/reset-password`	Đổi password bằng reset token.	Public	Global apiLimiter; một số flow có Redis/domain limit riêng.

POST /api/v1/auth/register

POST Auth varies apiLimiter

Endpoint này dùng để đăng ký user, trả token pair. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/register \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/register"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/login

POST Auth varies apiLimiter

Endpoint này dùng để đăng nhập bằng email/username + password. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/login \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/login"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/forgot-password

POST Auth varies apiLimiter

Endpoint này dùng để tạo reset token và enqueue email. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/forgot-password \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/forgot-password"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/profile

POST Auth required apiLimiter

Endpoint này dùng để update profile. [CẦN XÁC NHẬN] service chỉ trả updated. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/profile \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/profile"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/refresh-token

POST Auth varies apiLimiter

Endpoint này dùng để rotate refresh token từ x-refresh-token. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Có nếu auth refresh/logout	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/refresh-token \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/refresh-token"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

GET /api/v1/auth/me

GET Auth required apiLimiter

Endpoint này dùng để lấy user hiện tại, cache Redis 30s. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/auth/me \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/me"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/logout

POST Auth required apiLimiter

Endpoint này dùng để blacklist access token và revoke refresh token. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Có nếu auth refresh/logout	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/logout \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/logout"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/resend-verify-email

POST Auth required apiLimiter

Endpoint này dùng để gửi lại email verify. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Có	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/resend-verify-email \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/resend-verify-email"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/verify-email

POST Auth varies apiLimiter

Endpoint này dùng để verify email bằng token. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/verify-email \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/verify-email"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/validate/email

POST Auth varies apiLimiter

Endpoint này dùng để check Bloom filter email availability. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/validate/email \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/validate/email"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/validate/username

POST Auth varies apiLimiter

Endpoint này dùng để check Bloom filter username availability. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/validate/username \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/validate/username"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

GET /api/v1/auth/reset-password/validate

GET Auth varies apiLimiter

Endpoint này dùng để validate reset token. [CẦN XÁC NHẬN] luôn valid true. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Không	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X GET http://localhost:3302/api/v1/auth/reset-password/validate \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/reset-password/validate"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.

POST /api/v1/auth/reset-password

POST Auth varies apiLimiter

Endpoint này dùng để đổi password bằng reset token. Gọi endpoint này khi client cần thao tác đúng phạm vi module auth.

Request

Header	Giá trị	Bắt buộc	Mô tả
Authorization	Bearer accessToken	Không/Tùy route	JWT access token nếu route protected
x-refresh-token	raw refresh token	Không	Refresh token header theo middleware

Parameter	Kiểu	Mô tả	Ví dụ
path params	string	Các phần :publicId, :username, :code nếu path có	cm123
query params	string/number	take, after, page, limit hoặc module-specific query	take=20

Field	Kiểu	Bắt buộc	Validation	Mô tả	Ví dụ giá trị
body	object	Tùy endpoint	Theo DTO Zod nếu route có validate()	Payload nghiệp vụ của endpoint	{"content":"Hello"}

Ví dụ request

curl -X POST http://localhost:3302/api/v1/auth/reset-password \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

200/201 — Thành công

Field	Kiểu	Luôn có?	Mô tả
success	boolean	Có	true khi request thành công
message	string	Không	Một số controller truyền message
data	object/array	Tùy endpoint	Dữ liệu trả về từ service
pagination	object	Với list	Cursor/offset pagination

{
  "success": true,
  "data": {
    "module": "auth",
    "endpoint": "/api/v1/auth/reset-password"
  }
}

Lỗi có thể xảy ra

HTTP Status	Error Code	Khi nào xảy ra	Cách xử lý ở client
401	UNAUTHORIZED	Unauthorized	Login lại hoặc refresh token.
400	VALIDATION_FAILED	Validation failed	Client sửa field sai.
404	NOT_FOUND	Resource not found	Refresh dữ liệu.
403	FORBIDDEN	Forbidden	Ẩn action trong UI.
500	INTERNAL_SERVER_ERROR	External dependency fail	On-call kiểm tra provider/log.

Ví dụ lỗi

{
  "success": false,
  "message": "Validation failed"
}

Ghi chú

Endpoint đi qua global apiLimiter.
Idempotency không được đảm bảo trừ khi service có upsert/unique constraint riêng.
permission.ts hiện là function rỗng, không dùng làm RBAC thật.