gohorsejobs/docs/API_SECURITY.md

🔐 API Security & Access Levels

Security layers, authentication methods, and RBAC for GoHorse Jobs API.

Last Updated: 2026-02-16

---

🛡️ Authentication Methods

Method	Header/Cookie	Used By
Bearer Token	Authorization: Bearer <token>	Mobile apps, external integrations
HttpOnly Cookie	jwt=<token>	Web Frontend (Next.js), Backoffice

Cookie Properties: HttpOnly, Secure (prod), SameSite=Lax

---

🔒 Security Middlewares

Middleware	File	Description
Auth	middleware/auth.go	JWT validation + RBAC
CORS	middleware/cors.go	Whitelist via CORS_ORIGINS
Rate Limiting	middleware/rate_limit.go	100 req/min per IP
Security Headers	middleware/security_headers.go	OWASP headers (XSS, CSP)
Sanitize	middleware/sanitize.go	XSS sanitization in JSON

---

🚦 Access Levels

Level	Description	Middleware
Public	Open to everyone	None
Authenticated	Requires valid JWT	HeaderAuthGuard
Role-Restricted	JWT + Specific Role	HeaderAuthGuard + adminOnly

---

🗺️ Route Permission Matrix

🟢 Public Routes

Method	Route	Description
GET	/	Root check
GET	/health	Health check
POST	/api/v1/auth/login	Login
POST	/api/v1/auth/register/candidate	Candidate register
POST	/api/v1/auth/register/company	Company register
GET	/api/v1/jobs	List jobs
GET	/api/v1/jobs/{id}	Job details
GET	/api/v1/companies/{id}	Company details
GET	/docs/*	Swagger UI

🟡 Authenticated Routes

Method	Route	Description
GET	/api/v1/users/me	Get own profile
PATCH	/api/v1/users/me/profile	Update profile
GET	/api/v1/notifications	Get notifications
POST	/api/v1/tokens	Save FCM token
GET	/api/v1/storage/upload-url	Get pre-signed URL
GET	/api/v1/conversations	List conversations
POST	/api/v1/applications	Apply for job

🟠 Recruiter / Company Admin

Requires: 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
PUT	/api/v1/applications/{id}/status	Update status

🔴 Admin / SuperAdmin

Requires: Role superadmin OR admin

Method	Route	Description
GET	/api/v1/users	List all users
POST	/api/v1/users	Create user
DELETE	/api/v1/users/{id}	Delete user
GET	/api/v1/admin/companies	List companies
PATCH	/api/v1/admin/companies/{id}/status	Update company status
GET	/api/v1/jobs/moderation	Moderate jobs
PATCH	/api/v1/jobs/{id}/status	Approve/reject job
GET	/api/v1/admin/email-templates	List email templates
PUT	/api/v1/admin/email-templates/{slug}	Update template
PUT	/api/v1/admin/email-settings	Update SMTP settings
POST	/api/v1/system/credentials	Save credentials
POST	/api/v1/system/cloudflare/purge	Purge cache

---

🧪 Testing Security

1. Public Access (200 OK)

curl https://api.gohorsejobs.com/api/v1/jobs

2. Protected without Token (401)

curl https://api.gohorsejobs.com/api/v1/users/me

3. Admin Route as Candidate (403)

curl -H "Authorization: Bearer <candidate_token>" \
  https://api.gohorsejobs.com/api/v1/users

4. Admin Route as Admin (200 OK)

curl -H "Authorization: Bearer <admin_token>" \
  https://api.gohorsejobs.com/api/v1/users

---

🔑 JWT Claims

{
  "sub": "019438a1-2b3c-...",
  "email": "user@example.com",
  "role": "admin",
  "tenant_id": "019438a2-3c4d-...",
  "exp": 1735200000,
  "iat": 1735113600
}

---

🛡️ Password Security

Feature	Implementation
Hashing	BCrypt (10 rounds)
Pepper	PASSWORD_PEPPER env var
Min Length	8 characters
JWT Secret	Min 32 characters