Home

API Documentation Index

Welcome to the NFC WESMUN API documentation. This wiki provides comprehensive documentation for all available APIs in the NFC WESMUN system.

---

Overview

The NFC WESMUN system is a Next.js application that provides NFC-based user management for the WESMUN conference. It includes:

• User authentication and authorization
• Role-based access control (RBAC)
• NFC link generation and scanning
• User profile management
• Comprehensive audit logging ⇒ Enhanced with old/new value tracking
• Bulk operations support
• CSV/PDF export functionality

API Endpoints Summary

Total: 32 API endpoints

In depth wiki pages for each section can be found linked below.

Note: Emergency admin users bypass all permission checks automatically. See Emergency Admin Bypass for details.

Authentication (4 endpoints)

In depth wiki page can be found here

• POST /api/auth/login - Authenticate user
• POST /api/auth/register - Register new user
• POST /api/auth/logout - End session
• GET /api/auth/validate - Check session validity

Users (10 endpoints)

In depth wiki page can be found here

• GET /api/users - List all users
• PATCH /api/users/[userId] - Update user
• DELETE /api/users/[userId] - Delete user
• PATCH /api/users/freeze/[userId] - Freeze/unfreeze user
• PATCH /api/users/bulk-update - Bulk update
• POST /api/users/bulk-delete - Bulk delete
• POST /api/users/create-data-only - Create delegate
• POST /api/users/create-data-only/bulk - Bulk create delegates
• GET /api/users/export - Export CSV/PDF
• POST /api/users/export - Export with filters

Admin (2 endpoints)

In depth wiki page can be found here

• GET /api/admin/pending-users - List pending approvals
• POST /api/admin/approve-user - Approve/reject user

NFC (3 endpoints)

In depth wiki page can be found here

• GET /api/users/update/[uuid] - Scan NFC link
• PATCH /api/users/update/[uuid] - Update via NFC
• POST /api/createNFC - Create NFC link

Audit (3 endpoints)

In depth wiki page can be found here

• GET /api/audit - List audit logs
• DELETE /api/audit/[id] - Delete log entry
• DELETE /api/audit/bulk-delete - Bulk delete logs

---

Data Models

Core Tables

• users - User accounts and authentication (includes is_frozen for account suspension)
• profiles - Event-specific user data (bags, attendance, diet)
• nfc_links - NFC UUID mappings
• roles - User role definitions
• audit_logs - System action tracking
• sessions - Active user sessions

Key Relationships

users (1) ←→ (1) profiles
users (1) ←→ (1) nfc_links
users (N)  → (1) roles
users (1) ←  (N) audit_logs (as actor)
users (1) ←  (N) audit_logs (as target)
users (1) ←  (N) sessions

---

Quick Start Examples

Login and Get Users

// Login
const loginRes = await fetch('/api/auth/login', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    credentials: 'include',
    body: JSON.stringify({
        email: 'user@example.com',
        password: 'password123'
    })
});

// Get all users
const usersRes = await fetch('/api/users', {
    credentials: 'include'
});
const {users} = await usersRes.json();

Scan NFC and Update

// Scan NFC
const scanRes = await fetch(`/api/nfc/${uuid}`, {
    credentials: 'include'
});
const userData = await scanRes.json();

// Update profile
await fetch(`/api/nfc/${uuid}/update`, {
    method: 'PATCH',
    headers: {'Content-Type': 'application/json'},
    credentials: 'include',
    body: JSON.stringify({
        bags_checked: true,
        attendance: true
    })
});

Create and Export Users

// Bulk create data-only users
await fetch('/api/users/create-data-only/bulk', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    credentials: 'include',
    body: JSON.stringify({
        users: [
            {email: 'user1@example.com', name: 'User One'},
            {email: 'user2@example.com', name: 'User Two'}
        ]
    })
});

// Export to CSV
const exportRes = await fetch(
    '/api/users/export?format=csv&attendance=true',
    {credentials: 'include'}
);
const blob = await exportRes.blob();
// Download file...

---

Common Error Codes

Code	Meaning	Common Causes
400	Bad Request	Missing fields, invalid format
401	Unauthorized	Not logged in, invalid session
403	Forbidden	Insufficient permissions
404	Not Found	Invalid UUID, user doesn't exist
500	Server Error	Database error, unexpected exception

---

Search & Filter

User Export Filters

?format=csv|pdf         # Export format
?attendance=true|false  # Filter by attendance
?bags=true|false        # Filter by bags checked
?diet=veg|nonveg       # Filter by diet
?mode=count            # Count only (no data)

Audit Log Filters

?limit=100             # Results per page (1-500)
?offset=0              # Skip N results
?action=nfc_scan       # Filter by action type
?search=john           # Search across fields

---

Development Tools

Environment Variables

DATABASE_URL=postgresql://user:password@ep-xxx.region.aws.neon.tech/dbname?sslmode=require
EMERGENCY_ADMIN_PASSWORD=password-for-super-admin
EMERGENCY_ADMIN_USERNAME=admin@wesmun.com
...

Database Setup

# Initialize/migrate database
npm run db:setup
# or
node scripts/syncDB.js --setup

# Verify database health
npm run db:check

For more information, see Scripts Documentation.

---

Documentation Navigation

I want to authenticate users: → Authentication API

I want to manage users: → User Management API → Admin API

I want to scan NFC tags: → NFC API

I want to track actions: → Audit API

I want to understand permissions: → Permissions & Roles

I want to handle errors: → Error Handling

I want TypeScript types: → Data Types

---

Extra Information

Base URL

Production: https://nfc.wesmun.com
Development: http://localhost:3000

Authentication

All API endpoints (except login and register) require authentication via HTTP-only session cookies. The session token is set automatically after successful login.

HTTP Status Codes

• 200 OK - Request succeeded
• 201 Created - Resource created successfully
• 204 No Content - Success with no response body
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Contributing

To update this documentation:

1. Edit Markdown files in /wiki directory
2. Follow existing format for consistency
3. Include code examples for all endpoints
4. Test all examples before committing
5. Update this index if adding new files

---