Authentication

Overview

The authentication system uses JWT (JSON Web Tokens) for stateless authentication with access and refresh token patterns.

Auth Endpoints

Method	Endpoint	Description
POST	`/auth/login`	Login with email/password
POST	`/auth/signup`	Register new user
POST	`/auth/logout`	Logout current user
POST	`/auth/forgot-password`	Request password reset
POST	`/auth/reset-password`	Reset password with token
POST	`/auth/refresh`	Refresh access token
POST	`/auth/verify-email`	Verify email address
GET	`/auth/me`	Get current user

Authenticate a user with email and password.

Request

POST /api/auth/login
Content-Type: application/json
 
{
  "email": "user@example.com",
  "password": "password123"
}

Response

{
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "talent",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 604800
}

Error Responses

// 400 Bad Request - Invalid input
{
  "message": "Email is required"
}
 
// 401 Unauthorized - Invalid credentials
{
  "message": "Invalid email or password"
}

Request

POST /api/auth/signup
Content-Type: application/json
 
{
  "email": "newuser@example.com",
  "password": "SecurePass123!",
  "firstName": "Jane",
  "lastName": "Smith",
  "role": "employer",
  "agreeToTerms": true
}

Response

{
  "user": {
    "id": "user_456",
    "email": "newuser@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "employer",
    "createdAt": "2024-01-15T11:00:00Z",
    "updatedAt": "2024-01-15T11:00:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Validation Rules

Field	Rules
`email`	Required, valid email format, max 254 chars
`password`	Required, min 8 chars, uppercase, lowercase, number, special char
`firstName`	Required, 2-50 chars, letters only
`lastName`	Required, 2-50 chars, letters only
`role`	Required, one of: `employer`, `talent`
`agreeToTerms`	Required, must be `true`

Forgot Password

Request a password reset email.

Request

POST /api/auth/forgot-password
Content-Type: application/json
 
{
  "email": "user@example.com"
}

Response

{
  "message": "Password reset email sent"
}

Reset Password

Reset password using the token from email.

Request

POST /api/auth/reset-password
Content-Type: application/json
 
{
  "token": "reset_token_from_email",
  "password": "NewSecurePass123!",
  "confirmPassword": "NewSecurePass123!"
}

Response

{
  "message": "Password reset successful"
}

Refresh Token

Get a new access token using the refresh token.

Request

POST /api/auth/refresh
Content-Type: application/json
 
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 604800
}

Get Current User

Get the authenticated user's profile.

Request

GET /api/auth/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response

{
  "id": "user_123",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "role": "talent",
  "avatar": "https://example.com/avatar.jpg",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Verify Email

Verify email address with token from email.

Request

POST /api/auth/verify-email
Content-Type: application/json
 
{
  "token": "verification_token_from_email"
}

Response

{
  "message": "Email verified successfully"
}

Token Management

Access Token

Short-lived (default: 7 days)
Sent in Authorization header
Used for API authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Refresh Token

Long-lived (default: 30 days)
Used to obtain new access tokens
Should be stored securely

Token Storage (Frontend)

// Store tokens after login
localStorage.setItem("hireable_access_token", accessToken);
localStorage.setItem("hireable_refresh_token", refreshToken);
localStorage.setItem("hireable_user", JSON.stringify(user));
 
// Clear on logout
localStorage.removeItem("hireable_access_token");
localStorage.removeItem("hireable_refresh_token");
localStorage.removeItem("hireable_user");

Security Considerations

HTTPS Only - All auth endpoints should use HTTPS in production
Token Expiry - Access tokens expire to limit exposure
Refresh Rotation - Consider rotating refresh tokens on use
Secure Storage - Use httpOnly cookies for refresh tokens in production
Rate Limiting - Implement rate limiting on auth endpoints
Password Hashing - Passwords are hashed with bcrypt

Environment Variables

# JWT Configuration
JWT_SECRET=your-secure-secret-key
JWT_EXPIRES_IN=7d
REFRESH_TOKEN_EXPIRES_IN=30d

On this page