Authentication - EaseLMS

Overview

EaseLMS uses Supabase authentication for API security. Most API endpoints require a valid Supabase authentication token in the request headers.

Authentication Flow

The API uses session-based authentication with Supabase:

User logs in via the /api/auth/login endpoint
Supabase creates a session and returns access tokens
Subsequent API requests include the session cookie
Middleware validates the session on protected routes

User Types

EaseLMS supports three user types:

user - Learners who can enroll in and take courses
instructor - Instructors who can create and manage courses
admin - Administrators with full system access

Endpoint

POST /api/auth/login

Request Body

string

required

User’s email address

string

required

User’s password

string

required

Type of user attempting to login: user, instructor, or admin

Example Request

curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "learner@example.com",
    "password": "secure_password",
    "userType": "user"
  }'

Success Response

object

The authenticated user object from Supabase

Show properties

string

User’s unique identifier (UUID)

string

User’s email address

string

Timestamp when user was created

object

The Supabase session object containing authentication tokens

Show properties

string

JWT access token for API requests

string

Token used to refresh the access token

number

Unix timestamp when the session expires

Example Success Response

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "learner@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "session": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "v1.refresh_token_here...",
    "expires_at": 1705328400
  }
}

Error Responses

Invalid Credentials

{
  "error": "Invalid login credentials"
}

Status: 401 Unauthorized

Wrong User Type

If a learner tries to login through the admin portal:

{
  "error": "Learner accounts cannot login through admin portal. Please use the learner login page."
}

Status: 403 Forbidden If an admin tries to login through the learner portal:

{
  "error": "Admin accounts cannot login through learner portal. Please use the admin login page."
}

Status: 403 Forbidden

Instructors can login through the admin portal and will be granted access.

Making Authenticated Requests

Using Session Cookies

After successful login, Supabase automatically sets session cookies. Include these cookies in subsequent requests:

curl -X GET https://your-domain.com/api/enrollments \
  -H "Cookie: sb-access-token=...; sb-refresh-token=..." \
  -H "Content-Type: application/json"

Using Authorization Header

Alternatively, you can use the access token in the Authorization header:

curl -X GET https://your-domain.com/api/enrollments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Checking Authentication Status

Protected endpoints will return 401 Unauthorized if the session is invalid or expired:

{
  "error": "Unauthorized"
}

User Permissions

Different endpoints require different permission levels:

Public Endpoints

These endpoints don’t require authentication:

GET /api/courses (published courses only)
GET /api/courses/[id] (published courses only)

Authenticated User Endpoints

These endpoints require any authenticated user:

GET /api/enrollments (returns user’s own enrollments)
POST /api/enrollments (self-enrollment)
GET /api/progress
POST /api/progress
GET /api/profile

Admin/Instructor Endpoints

These endpoints require admin or instructor privileges:

POST /api/courses (admin only)
GET /api/courses?all=true (all courses including drafts)
GET /api/users (admin only)
POST /api/users (admin only)
GET /api/admin/stats (admin only)

Permission Denied Response

If a user lacks required permissions:

{
  "error": "Forbidden"
}

Status: 403 Forbidden

Endpoint

POST /api/auth/signup

Request Body

string

required

New user’s email address

string

required

New user’s password

string

required

New user’s full name

string

required

Type of user account: user, instructor, or admin

Example Request

curl -X POST https://your-domain.com/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newlearner@example.com",
    "password": "secure_password123",
    "name": "John Doe",
    "userType": "user"
  }'

Logout

Endpoint

POST /api/auth/logout

Example Request

curl -X POST https://your-domain.com/api/auth/logout \
  -H "Cookie: sb-access-token=...; sb-refresh-token=..."

Password Reset

Request Password Reset

POST /api/auth/reset-password

Change Password

POST /api/auth/change-password

Row Level Security (RLS)

EaseLMS uses Supabase Row Level Security to protect data at the database level. The API includes two types of Supabase clients:

Regular Client

Used for user-scoped operations. RLS policies apply:

Users can only access their own enrollments
Users can only update their own progress
Users can only view their own profile

Service Role Client

Used for admin operations and bypasses RLS:

Admin user management
Cross-user enrollment operations
System-wide statistics

The service role key should never be exposed to the client. It’s only used server-side in API routes.

Security Best Practices

Always use HTTPS in production

Never send authentication credentials over unencrypted HTTP connections.

Store tokens securely

If storing tokens on the client, use secure, httpOnly cookies or secure storage mechanisms.

Validate user types

The API validates user types on login to prevent unauthorized access to admin/instructor features.

Handle token expiration

Implement token refresh logic to handle expired sessions gracefully.

Never expose service role keys

Keep SUPABASE_SERVICE_ROLE_KEY private and only use it server-side.

Next Steps

API Overview

Learn about API structure and response formats

Courses Endpoints

Start working with the Courses API

​Overview

​Authentication Flow

​User Types

​Login

​Endpoint

​Request Body

​Example Request

​Success Response

​Example Success Response

​Error Responses

​Invalid Credentials

​Wrong User Type

​Making Authenticated Requests

​Using Session Cookies

​Using Authorization Header

​Checking Authentication Status

​User Permissions

​Public Endpoints

​Authenticated User Endpoints

​Admin/Instructor Endpoints

​Permission Denied Response

​Signup

​Endpoint

​Request Body

​Example Request

​Logout

​Endpoint

​Example Request

​Password Reset

​Request Password Reset

​Change Password

​Row Level Security (RLS)

​Regular Client

​Service Role Client

​Security Best Practices

​Next Steps

API Overview

Courses Endpoints

Overview

Authentication Flow

User Types

Login

Endpoint

Request Body

Example Request

Success Response

Example Success Response

Error Responses

Invalid Credentials

Wrong User Type

Making Authenticated Requests

Using Session Cookies

Using Authorization Header

Checking Authentication Status

User Permissions

Public Endpoints

Authenticated User Endpoints

Admin/Instructor Endpoints

Permission Denied Response

Signup

Endpoint

Request Body

Example Request

Logout

Endpoint

Example Request

Password Reset

Request Password Reset

Change Password

Row Level Security (RLS)

Regular Client

Service Role Client

Security Best Practices

Next Steps