Skip to main content

​
Overview

The MND API uses passwordless magic link authentication. Users receive a secure token via email (simulated in development) that creates a session lasting 7 days.

​
Authentication Flow

POST /api/auth/send-link
Content-Type: application/json

{
  "email": "student@example.com"
}

​
Request Body

​
email
string
required
User’s email address. Must be a valid email format.

​
Response Fields

​
success
boolean
Indicates if the magic link was generated successfully
​
message
string
User-friendly confirmation message
​
_dev
object
Development-only fields (removed in production)

​
Error Responses

Missing Email (400) 
{
  "error": "Email is required",
  "message": "Please provide a valid email address"
}
Invalid Email Format (400) 
{
  "error": "Invalid email",
  "message": "Please provide a valid email address"
}

GET /api/auth/verify?token=a1b2c3d4e5f6...

​
Query Parameters

​
token
string
required
Magic link token received via email (valid for 15 minutes)

​
Response Fields

​
success
boolean
Indicates if authentication was successful
​
authToken
string
JWT-style authentication token valid for 7 days. Use this in the Authorization header for protected endpoints.
​
user
object
Authenticated user information

​
Error Responses

Missing Token (400) 
{
  "error": "Token is required",
  "message": "Please provide a valid token"
}
Invalid/Expired/Used Token (401) 
{
  "error": "Verification failed",
  "message": "Token expired"
}

​
Using Auth Tokens

After successful verification, include the auth token in the Authorization header: 
Authorization: Bearer x9y8z7w6v5u4...

​
Example Protected Request

curl -X GET http://localhost:3000/api/favorites \
  -H "Authorization: Bearer x9y8z7w6v5u4..."

​
Get User Profile

GET /api/profile
Authorization: Bearer x9y8z7w6v5u4...

​
Headers

​
Authorization
string
required
Bearer token obtained from verification endpoint

​
Logout

POST /api/auth/logout
Authorization: Bearer x9y8z7w6v5u4...
Invalidates the auth token. The token can no longer be used for authenticated requests.

​
Token Lifecycle

  • Generated: On POST /api/auth/send-link
  • Expires: 15 minutes
  • Single Use: Cannot be reused after verification
  • Storage: Server-side in users.json

​
Auth Token

  • Generated: On successful magic link verification
  • Expires: 7 days
  • Revocation: Explicit logout or expiration
  • Storage: Server-side in users.json

​
Automatic Cleanup

Expired tokens are automatically removed:
  • When new magic links are generated
  • During token validation

​
Security Considerations

The current implementation is designed for development. For production:
  • Integrate a real email service (SendGrid, AWS SES, etc.)
  • Use HTTPS for all requests
  • Implement rate limiting on auth endpoints
  • Store tokens in a secure database (not JSON files)
  • Add CSRF protection
  • Consider shorter token expiration times

​
Protected Endpoints

The following endpoints require authentication:
  • GET /api/favorites
  • POST /api/favorites
  • PUT /api/favorites/:id
  • DELETE /api/favorites/:id
All return 401 Unauthorized if the Authorization header is missing or invalid: 
{
  "error": "Unauthorized",
  "message": "Authentication required"
}