API Documentation

EduNest LMS is a Next.js 16 (App Router) application. There is no separate API server — every endpoint is a route handler living under src/app/api/. They run on the same host as the storefront and admin panel, so the base URL is simply your site origin.

Base URL (local): http://localhost:3000 Base URL (production): https://your-domain.com

There are three families of endpoints, each authenticated differently:

Authentication

EduNest uses cookie-based sessions for the first-party surfaces (storefront, portal, instructor, admin) and a separate bearer-key scheme for the optional public REST API add-on.

Admin session (admin_token)

Admins sign in at POST /api/v1/admin/auth/login. On success the server sets an HTTP-only admin_token cookie holding a signed JWT. Every /api/v1/admin/* route reads that cookie, and most write routes additionally enforce a permission (RBAC) via requirePermission(...) — there is no global middleware, the check is per-route.

POST /api/v1/admin/auth/login
Content-Type: application/json

{ "email": "admin@example.com", "password": "••••••••" }

Customer / learner session (member_session)

Learners register and verify via email OTP, then receive a member_session cookie (JWT). All /api/v1/portal/* routes require it.

Public REST API add-on (bearer edu_ keys)

The REST API & Keys add-on (src/product/addons/api/) exposes a read-only data API authenticated by an API key rather than a session. Keys are issued under Admin → API Keys, are stored only as a SHA-256 hash, and carry scopes. Send the raw key either way:

Authorization: Bearer edu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Key:     edu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Each endpoint requires a scope; a key missing the scope is rejected with 403. The scopes are courses, customers, enrollments, orders (or * for all).

Interactive API docs (OpenAPI)

EduNest ships a hand-maintained OpenAPI 3.0 document and a Swagger UI page.

Both are protected by HTTP Basic Auth, enforced before the route is reachable. Credentials come from environment variables, with built-in fallbacks:

API_DOCS_USER=admin        # default: admin
API_DOCS_PASS=Password@1    # default: Password@1

Both pages send noindex, nofollow (x-robots-tag) so they never appear in search engines. The spec is served force-static.

# Download the live spec (Basic Auth required)
curl -u "$API_DOCS_USER:$API_DOCS_PASS" \
  http://localhost:3000/api/openapi.json -o edunest-openapi.json

The bundled /api/openapi.json documents the public, customer-portal, checkout and a representative slice of the admin endpoints. The REST API add-on publishes its own OpenAPI 3.1 spec separately at /api/v1/ext/api/openapi (see below).

Endpoint reference

The tables below list real route handlers under src/app/api/. List endpoints generally accept query params; :id / :slug are path params.

Storefront auth (public + portal)

Courses (catalog)

Enrollments & progress (portal)

Orders & checkout

Customers (admin)

Admin catalog & content

License

REST API add-on (/api/v1/ext/api/v1/*)

These are dispatched through the catch-all /api/v1/ext/[addon]/[...path] route into the add-on's handler map. Every endpoint is read-only and requires the scope shown.

List endpoints accept limit (≤ 100, default 50) and offset (default 0) and return an envelope:

{ "data": [ /* rows */ ], "limit": 50, "offset": 0 }

Request example (REST add-on)

curl https://your-domain.com/api/v1/ext/api/v1/courses?limit=10 \
  -H "Authorization: Bearer edu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "id": 42,
      "slug": "intro-to-data-science",
      "title": "Intro to Data Science",
      "level": "beginner",
      "price_cents": 4999,
      "currency": "USD",
      "status": "published",
      "rating_avg": 4.7,
      "enrollment_count": 1280
    }
  ],
  "limit": 10,
  "offset": 0
}

The same key also works via the X-API-Key header:

curl https://your-domain.com/api/v1/ext/api/v1/enrollments \
  -H "X-API-Key: edu_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Error responses

First-party routes return JSON { "error": "..." } with the appropriate HTTP status. The REST add-on uses the same shape:

{ "error": "This key is missing the 'orders' scope." }

© CreativeCape Solutions · creative-cape.com · support@creative-cape.com