gohorsejobs/docs/API_SECURITY.md

🔐 API Security & Access Levels

This document details the security layers, authentication methods, and role-based access control (RBAC) for the GoHorse Jobs API. Use this guide to verify and test route protection.

🛡️ Authentication Methods

1. Bearer Token (JWT)

   • Header: Authorization: Bearer <token>
   • Used by: Mobile apps, external integrations, simple API tests.

2. HttpOnly Cookie

   • Cookie Name: jwt
   • Used by: Web Frontend (Next.js), Backoffice.
   • Properties: HttpOnly, Secure (in prod), SameSite=Lax.

🚦 Access Levels

Level	Description	Middleware
Public	Open to everyone (Guests). No check performed.	None
Authenticated	Requires a valid JWT (Header or Cookie).	HeaderAuthGuard
Role-Restricted	Requires valid JWT + Specific Role claim.	HeaderAuthGuard + RequireRoles(...)

🗺️ Route Permission Matrix

🟢 Public Routes

Method	Route	Description	Notes
POST	/api/v1/auth/login	User Login	Returns JWT + Cookie
POST	/api/v1/auth/register	Candidate Register	Creates candidate user
POST	/api/v1/companies	Company Register	Creates company + admin
GET	/api/v1/jobs	List Jobs	Public search/list
GET	/api/v1/jobs/{id}	Get Job	Public details
GET	/docs/*	Swagger UI	API Documentation

🟡 Authenticated Routes (Any Logged User)

Requirement: Valid JWT.

Method	Route	Description
GET	/api/v1/users/me	Get Own Profile
PATCH	/api/v1/users/{id}	Update Own Profile (Self-check in handler)
GET	/api/v1/notifications	Get Own Notifications
POST	/api/v1/applications	Apply for Job (Candidate)
POST	/api/v1/storage/upload-url	Get S3 Upload URL
POST	/api/v1/storage/download-url	Get S3 Download URL
DELETE	/api/v1/storage/files	Delete S3 File

🟠 Recruiter / CompanyAdmin Routes

Requirement: Role admin OR recruiter.

Method	Route	Description
POST	/api/v1/jobs	Create Job
PUT	/api/v1/jobs/{id}	Update Job
DELETE	/api/v1/jobs/{id}	Delete Job
GET	/api/v1/applications	List Applications (for own jobs)
PUT	/api/v1/applications/{id}/status	Update Application Status

🔴 Admin / SuperAdmin Routes (Backoffice)

Requirement: Role superadmin OR admin.

Method	Route	Description	Middleware Check
GET	/api/v1/users	List All Users	adminOnly
POST	/api/v1/users	Create User (Staff)	adminOnly
DELETE	/api/v1/users/{id}	Delete User	adminOnly
GET	/api/v1/users/roles	List System Roles	adminOnly
GET	/api/v1/companies	List Companies (Full)	adminOnly
PATCH	/api/v1/companies/{id}/status	Activate/Ban Company	adminOnly
GET	/api/v1/jobs/moderation	Moderate Jobs	adminOnly
PATCH	/api/v1/jobs/{id}/status	Approve/Reject Job	adminOnly
POST	/api/v1/jobs/{id}/duplicate	Admin Duplicate Job	adminOnly
GET	/api/v1/tags	List Tags	adminOnly
POST	/api/v1/tags	Create Tag	adminOnly
PATCH	/api/v1/tags/{id}	Update Tag	adminOnly
GET	/api/v1/candidates	List All Candidates	adminOnly
GET	/api/v1/audit/logins	View Audit Logs	adminOnly

🧪 Testing Security

1. Test Public Access (Should Succeed)

curl http://localhost:8521/api/v1/jobs

2. Test Protected Route without Token (Should Fail 401)

curl http://localhost:8521/api/v1/users/me
# Expected: 401 Unauthorized

3. Test Admin Route as Candidate (Should Fail 403)

1. Login as Candidate -> Get Token A
2. Call Admin Route:

curl -H "Authorization: Bearer <TOKEN_A>" http://localhost:8521/api/v1/audit/logins
# Expected: 403 Forbidden

4. Test Admin Route as Admin (Should Succeed)

1. Login as SuperAdmin -> Get Token B
2. Call Admin Route:

curl -H "Authorization: Bearer <TOKEN_B>" http://localhost:8521/api/v1/audit/logins
# Expected: 200 OK