Authentication

The Jose Madrid Salsa API uses NextAuth.js with JWT-based sessions for authentication. All protected endpoints require a valid session, which is established through either credentials login or OAuth provider sign-in.

Authentication Methods

{
  "email": "user@example.com",
  "password": "your-password"
}

{
  "email": "user@example.com",
  "password": "minimum8chars",
  "name": "Optional Name"
}

Session Structure

Sessions use the JWT strategy with a 30-day maximum age. The session object available to your application includes:

JWT Token Enrichment

The JWT callback enriches tokens with additional data:

User Roles

The platform defines six roles used for authorization:

Role-Based Access Control (RBAC)

Authorization is enforced through two complementary systems: role checks and granular permissions.

Role Checks

The withAuth middleware and requireRole helper restrict endpoints by role:

import { withAuth } from '@/lib/middleware/api-helpers'
import { UserRole } from '@prisma/client'

export const POST = withAuth(async (request) => {
  // Only ADMIN users reach this handler
  return NextResponse.json({ success: true })
}, { roles: [UserRole.ADMIN] })

Granular Permissions

Permissions follow a resource:action naming convention (e.g., products:read, orders:write). They are checked against the RolePermission table in the database, with a fallback to default permissions if the table is empty or missing.

import { requirePermission } from '@/lib/rbac'

export async function GET(req: NextRequest) {
  const user = await requirePermission('products:read')
  // User has products:read permission
}

Permission Categories

Default Role Permissions

• ADMIN / DEVELOPER: All permissions
• STAFF: Orders (read/write/export/import/modify/print-labels), Products (read/write/bulk/import), Users (read), Content (read/write), Analytics (read), Messaging (all), Gift Certificates (read/write), Locations (read), Events (read), SEO (read), AI analytics (view)
• CUSTOMER / WHOLESALE: No admin permissions (access own resources only)
• FUNDRAISER: Fundraiser portal permissions only

Middleware Helpers

The lib/middleware/api-helpers.ts module provides composable wrappers for API route handlers.

withAuth

Wraps a handler with authentication and optional role/permission checks.

withAuth(handler, {
  required: true,       // Require authentication (default: true)
  roles: [UserRole.ADMIN], // Restrict to specific roles
  permission: 'orders:read' // Require a specific permission
})

Presets

Composing Middleware

Multiple middleware wrappers can be composed together using the compose helper:

import { compose, withAuth, withRateLimit } from '@/lib/middleware/api-helpers'
import { RATE_LIMITS } from '@/lib/rate-limiter'

export const POST = compose(
  (h) => withAuth(h, { roles: [UserRole.ADMIN] }),
  (h) => withRateLimit(h, RATE_LIMITS.API_GENERAL)
)(async (request) => {
  return NextResponse.json({ success: true })
})

Making Authenticated Requests

Include the NextAuth session cookie in your requests:

curl -X GET https://josemadrid.net/api/orders \
  -H "Cookie: next-auth.session-token=your-session-token" \
  -H "Content-Type: application/json"

For browser-based clients, the session cookie is set automatically after sign-in. For programmatic access, authenticate via the NextAuth credentials endpoint first to obtain a session token.