Authentication - Extracurricular Management System

Overview

The Extracurricular Management System API uses JWT (JSON Web Token) authentication to secure endpoints. After registering or logging in, you’ll receive a token that must be included in subsequent requests.

Authentication Flow

Create an account or authenticate with existing credentials

Receive JWT Token

The API returns a JWT token in the response

Include Token in Requests

Add the token to the Authorization header for protected endpoints

Token Validation

The server validates your token on each request

User Registration

Endpoint

POST /api/auth/register

This endpoint is publicly accessible and does not require authentication.

Request Body

firstName

string

required

User’s first name

lastName

string

required

User’s last name

string

required

Valid email address (must be unique)

password

string

required

Password (minimum 6 characters)

role

string

required

User role: STUDENT, ORGANIZER, or ADMIN

phoneNumber

string

Optional phone number

Role-Specific Fields

For STUDENT:

studentID

string

Student identifier (e.g., “S123456”)

major

string

Student’s major/field of study

yearOfStudy

integer

Current year of study

For ORGANIZER:

organizationName

string

Name of the organization

departmentAffiliation

string

Department affiliation

For ADMIN:

adminLevel

string

Admin level (defaults to STANDARD_ADMIN for public registration)

Registration Examples

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "password": "securepass123",
    "role": "STUDENT",
    "studentID": "S123456",
    "major": "Computer Science",
    "yearOfStudy": 3
  }'

Registration Response

{
  "statusCode": 201,
  "message": "User Registered Successfully",
  "data": null,
  "timestamp": "2024-03-07T10:45:30"
}

Authenticate with existing credentials to receive a JWT token.

Endpoint

POST /api/auth/login

This endpoint is publicly accessible and does not require authentication.

Request Body

string

required

User’s email address

password

string

required

User’s password

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepass123"
  }'

{
  "statusCode": 200,
  "message": "Login Successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqYW5lLmRvZUB1bml2ZXJzaXR5LmVkdSIsImlhdCI6MTcwOTgxNDMzMCwiZXhwIjoxNzA5OTAwNzMwfQ.xYz123...",
    "email": "[email protected]",
    "role": "STUDENT",
    "id": 42,
    "firstName": "Jane",
    "lastName": "Doe",
    "message": null
  },
  "timestamp": "2024-03-07T10:45:30"
}

Response Fields

data.token

string

JWT token for authentication (valid for 24 hours by default)

data.email

string

User’s email address

data.role

string

User’s role: STUDENT, ORGANIZER, or ADMIN

data.id

long

User’s unique identifier (userID)

data.firstName

string

User’s first name

data.lastName

string

User’s last name

Using JWT Tokens

After obtaining a JWT token from login, include it in the Authorization header for all protected endpoints.

Header Format

Authorization: Bearer <your-jwt-token>

The token must be prefixed with Bearer (note the space after “Bearer”).

Authentication Examples

curl -X GET http://localhost:8080/api/events/managed \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqYW5lLmRvZUB1bml2ZXJzaXR5LmVkdSIsImlhdCI6MTcwOTgxNDMzMCwiZXhwIjoxNzA5OTAwNzMwfQ.xYz123..."

JWT Token Details

Token Structure

JWT tokens follow the standard three-part structure:

header.payload.signature

Example token:

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqYW5lLmRvZUB1bml2ZXJzaXR5LmVkdSIsImlhdCI6MTcwOTgxNDMzMCwiZXhwIjoxNzA5OTAwNzMwfQ.xYz123...

Token Claims

The payload contains the following claims:

sub (subject): User’s email address
iat (issued at): Token creation timestamp (Unix time)
exp (expiration): Token expiration timestamp (Unix time)

Token Expiration

Default expiration: 24 hours (86400000 milliseconds)
Configurable via expirationInt property
Expired tokens will result in 401 Unauthorized responses

Tokens expire after 24 hours by default. Users must log in again to obtain a new token.

Token Security

Tokens are signed using HMAC-SHA algorithm
Secret key is configured via secreteJwtString property
Tokens are validated on every request to protected endpoints

Public vs Protected Endpoints

Public Endpoints (No Authentication Required)

POST /api/auth/register - User registration
POST /api/auth/login - User login
GET /api/events/** - Public event viewing (guests can view events)
GET /api/uploads/** - Public access to uploaded assets
GET /actuator/health - Health check
GET /actuator/info - API information

Protected Endpoints (Authentication Required)

All other endpoints require a valid JWT token in the Authorization header.

Role-Based Access Control

Some endpoints require specific roles:

@PreAuthorize("hasRole('ORGANIZER')")
GET /api/events/managed

Error Responses

401 Unauthorized

Returned when:

No token is provided
Token is malformed
Token signature is invalid
Token has expired

{
  "statusCode": 401,
  "message": "Unauthorized: Invalid or expired token",
  "data": null,
  "timestamp": "2024-03-07T10:50:00"
}

403 Forbidden

Returned when:

Token is valid but user lacks required role
User account is suspended or inactive

{
  "statusCode": 403,
  "message": "Access denied: Insufficient permissions",
  "data": null,
  "timestamp": "2024-03-07T10:51:30"
}

Best Practices

Store Tokens Securely

Use localStorage or sessionStorage for web applications
Never store tokens in cookies without HttpOnly and Secure flags
Use secure storage mechanisms for mobile apps

Handle Token Expiration

Implement automatic token refresh or re-login flow
Clear stored tokens on logout
Handle 401 responses by redirecting to login

Use HTTPS in Production

Always use HTTPS to prevent token interception
Never send tokens over unencrypted HTTP connections

Implement Logout

Clear stored tokens on client-side logout
Consider implementing token revocation for enhanced security

Security Configuration

The API uses Spring Security with the following configuration:

CSRF Protection: Disabled (stateless JWT authentication)
Session Management: Stateless (no server-side sessions)
CORS: Enabled with configured origins
Password Encoding: BCrypt hashing algorithm

Next Steps

API Overview

Learn about API conventions and response formats

Explore Endpoints

Browse available API endpoints

Overview

Endpoints

​Overview

​Authentication Flow

​User Registration

​Endpoint

​Request Body

​Role-Specific Fields

​Registration Examples

​Registration Response

​User Login

​Endpoint

​Request Body

​Login Examples

​Login Response

​Response Fields

​Using JWT Tokens

​Header Format

​Authentication Examples

​JWT Token Details

​Token Structure

​Token Claims

​Token Expiration

​Token Security

​Public vs Protected Endpoints

​Public Endpoints (No Authentication Required)

​Protected Endpoints (Authentication Required)

​Role-Based Access Control

​Error Responses

​401 Unauthorized

​403 Forbidden

​Best Practices

​Security Configuration

​Next Steps

API Overview

Explore Endpoints

Build docs developers (and LLMs) love

Overview

Authentication Flow

User Registration

Endpoint

Request Body

Role-Specific Fields

Registration Examples

Registration Response

User Login

Endpoint

Request Body

Login Examples

Login Response

Response Fields

Using JWT Tokens

Header Format

Authentication Examples

JWT Token Details

Token Structure

Token Claims

Token Expiration

Token Security

Public vs Protected Endpoints

Public Endpoints (No Authentication Required)

Protected Endpoints (Authentication Required)

Role-Based Access Control

Error Responses

401 Unauthorized

403 Forbidden

Best Practices

Security Configuration

Next Steps