Authentication

Overview

The PZ Packs API uses Better Auth for authentication. API requests are authenticated using session-based cookies with Discord OAuth2 as the authentication provider.

Authentication Flow

1. User Authentication

Users authenticate through the web application using Discord OAuth2:

GET /auth/discord

This redirects to Discord for authorization. After successful authentication, Better Auth creates a session and sets a secure, HTTP-only cookie. Upon successful authentication, a session cookie is set:

better-auth.session_token=<token_value>

Cookie properties:

Name: better-auth.session_token
HTTP Only: Yes (not accessible via JavaScript)
Secure: Yes (HTTPS only in production)
SameSite: Set based on CORS configuration
Max Age: 5 minutes (with refresh mechanism)

Better Auth implements session caching with a 5-minute cache duration to reduce database queries while maintaining security.

Making Authenticated Requests

Browser Requests

When making requests from a browser (same origin or with CORS credentials), cookies are automatically included:

fetch('http://localhost:3001/modpacks/my', {
  method: 'GET',
  credentials: 'include', // Important: include cookies
  headers: {
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

cURL Requests

For testing with cURL, include the session cookie:

curl -X GET http://localhost:3001/modpacks/my \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
  --cookie-jar cookies.txt \
  --cookie cookies.txt

You can extract your session token from browser DevTools > Application > Cookies or by inspecting the Set-Cookie header after authentication.

Programmatic Access

For applications consuming the API, maintain the session cookie across requests:

import { createAuthClient } from '@org/auth/client';

const client = createAuthClient({
  baseURL: 'http://localhost:3001',
  credentials: 'include'
});

// Client automatically handles cookie management
const response = await client.fetch('/modpacks/my');

Session Management

Better Auth handles session lifecycle automatically:

Session Creation

Sessions are created upon successful Discord OAuth authentication:

POST /auth/discord/callback

Session Validation

The API validates sessions on protected endpoints using the auth macro:

{
  auth: true,
  permission: { resource: 'modpack', action: 'read' }
}

Validation process:

Extract session token from cookie
Validate token against database/cache
Load user data and role
Check permissions if specified

Session Expiration

Sessions use cookie caching with automatic refresh:

Cache Duration: 5 minutes
Refresh: Automatic on valid requests
Expiration: Handled by Better Auth

Getting Current Session

Retrieve the current authenticated user:

curl -X GET http://localhost:3001/auth/session \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"

Response:

{
  "session": {
    "id": "session-id",
    "userId": "user-id",
    "expiresAt": "2026-03-01T12:00:00Z"
  },
  "user": {
    "id": "user-id",
    "name": "Discord User",
    "email": "user@example.com",
    "role": "user",
    "image": "https://cdn.discordapp.com/avatars/..."
  }
}

Logout

Invalidate the current session:

curl -X POST http://localhost:3001/auth/sign-out \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"

This removes the session from the database and clears the cookie.

Authorization and Permissions

Permission Checking

Protected endpoints specify required permissions:

{
  auth: true,
  permission: { resource: 'modpack', action: 'create' }
}

The API checks if the authenticated user’s role includes the required permission.

Role-Based Access

User Role:

Standard modpack operations (create, read, update, delete)
Mod management within own modpacks
Member management for own modpacks

Admin Role:

All user permissions
Global mod updates (mod:update-all)
Admin panel access (admin:access)

Resource-Level Authorization

Beyond role permissions, controllers enforce resource-level rules: Modpack ownership:

Only owners can update or archive modpacks
Only owners can manage members
Owners and members can add/remove mods

Example authorization check:

const isOwner = modpack.owner === user.id;
const isMember = modpack.members.some(m => m.userId === user.id);

if (!isOwner && !isMember && !modpack.isPublic) {
  return status(403, { error: { message: 'Access denied' } });
}

Error Responses

401 Unauthorized

Returned when no valid session is found:

{
  "message": "Unauthorized"
}

Common causes:

Missing session cookie
Expired or invalid session token
Session not found in database

403 Forbidden

Returned when authenticated but lacking permission:

{
  "message": "Do not have permission"
}

Common causes:

User role lacks required permission
Not the owner of the resource (for owner-only actions)
Not a member of the modpack (for member actions)

CORS and Credentials

The API is configured to support cross-origin requests with credentials:

cors({
  origin: env.ORIGIN_ALLOWED,  // Whitelist via environment variable
  credentials: true,            // Allow cookies
  allowedHeaders: ['Content-Type', 'Authorization']
})

Allowed Origins

Configure trusted origins in the environment:

ORIGIN_ALLOWED="http://localhost:3000,https://pzpacks.com"

Always include credentials when making cross-origin requests, otherwise cookies won’t be sent:

fetch(url, { credentials: 'include' })

Security Considerations

Session Security

HTTP-Only Cookies: Prevents XSS attacks
Secure Flag: Ensures HTTPS-only transmission in production
SameSite: Protects against CSRF attacks
Database-Backed: Sessions stored in PostgreSQL with cache layer

Best Practices

Never expose session tokens in client-side code or logs
Use HTTPS in production to protect cookies in transit
Implement CSRF protection if building forms that modify data
Rotate secrets regularly for Discord OAuth credentials
Monitor sessions for suspicious activity

Environment Variables

Required authentication configuration:

# Discord OAuth
DISCORD_CLIENT_ID="your-client-id"
DISCORD_CLIENT_SECRET="your-client-secret"

# CORS
ORIGIN_ALLOWED="http://localhost:3000,https://pzpacks.com"

# Database (for session storage)
DATABASE_URL="postgresql://..."
SECONDARY_DATABASE_URL="redis://..."  # For session caching

Better Auth Endpoints

Better Auth provides these endpoints automatically:

Endpoint	Method	Description
`/auth/discord`	GET	Initiate Discord OAuth flow
`/auth/discord/callback`	GET	Handle OAuth callback
`/auth/session`	GET	Get current session
`/auth/sign-out`	POST	Sign out and clear session

For a complete list of Better Auth endpoints, see the Better Auth documentation or the OpenAPI docs at /docs in development mode.

Testing Authentication

1. Authenticate via Browser

Navigate to http://localhost:3000/auth/discord
Complete Discord OAuth flow
Open DevTools > Application > Cookies
Copy the better-auth.session_token value

2. Use Token in API Requests

# Store token in variable
SESSION_TOKEN="your-token-here"

# Make authenticated request
curl -X GET http://localhost:3001/modpacks/my \
  -H "Cookie: better-auth.session_token=$SESSION_TOKEN"

3. Test Permission Levels

# User action (should succeed for users)
curl -X POST http://localhost:3001/modpacks \
  -H "Cookie: better-auth.session_token=$SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Pack", "isPublic": true}'

# Admin action (requires admin role)
curl -X POST http://localhost:3001/mods/update-all \
  -H "Cookie: better-auth.session_token=$SESSION_TOKEN"

Getting Started

Endpoints

Overview

Authentication Flow

1. User Authentication

Making Authenticated Requests

Browser Requests

cURL Requests

Programmatic Access

Session Management

Session Creation

Session Validation

Session Expiration

Getting Current Session

Logout

Authorization and Permissions

Permission Checking

Role-Based Access

Resource-Level Authorization

Error Responses

401 Unauthorized

403 Forbidden

CORS and Credentials

Allowed Origins

Security Considerations

Session Security

Best Practices

Environment Variables

Better Auth Endpoints

Testing Authentication

1. Authenticate via Browser

2. Use Token in API Requests

3. Test Permission Levels

Next Steps

API Overview

Modpack Endpoints

Build docs developers (and LLMs) love

Getting Started

Endpoints

Documentation Index

​Overview

​Authentication Flow

​1. User Authentication

​2. Session Cookie

​Making Authenticated Requests

​Browser Requests

​cURL Requests

​Programmatic Access

​Session Management

​Session Creation

​Session Validation

​Session Expiration

​Getting Current Session

​Logout

​Authorization and Permissions

​Permission Checking

​Role-Based Access

​Resource-Level Authorization

​Error Responses

​401 Unauthorized

​403 Forbidden

​CORS and Credentials

​Allowed Origins

​Security Considerations

​Session Security

​Best Practices

​Environment Variables

​Better Auth Endpoints

​Testing Authentication

​1. Authenticate via Browser

​2. Use Token in API Requests

​3. Test Permission Levels

​Next Steps

API Overview

Modpack Endpoints

Build docs developers (and LLMs) love

Overview

Authentication Flow

1. User Authentication

2. Session Cookie

Making Authenticated Requests

Browser Requests

cURL Requests

Programmatic Access

Session Management

Session Creation

Session Validation

Session Expiration

Getting Current Session

Logout

Authorization and Permissions

Permission Checking

Role-Based Access

Resource-Level Authorization

Error Responses

401 Unauthorized

403 Forbidden

CORS and Credentials

Allowed Origins

Security Considerations

Session Security

Best Practices

Environment Variables

Better Auth Endpoints

Testing Authentication

1. Authenticate via Browser

2. Use Token in API Requests

3. Test Permission Levels

Next Steps