API Documentation

Build integrations with the ScholarSync platform

REST API

JSON over HTTPS

All endpoints follow REST conventions with JSON request/response bodies. Snake_case field naming is used consistently across all services.

JWT Authentication

Token-based security

Secure authentication with signature verification, token binding (tbf, tbi, tbv claims), rate limiting, and Redis-backed token blacklisting.

Multi-Tenant

Organization-scoped

All data is organization-scoped via Row Level Security. Include the X-Organization-ID header with every request for proper tenant isolation.

API Gateway

All API requests are routed through the API Gateway (port 9000) which handles authentication, rate limiting, and service routing. The gateway uses a hash-based routing registry to direct requests to the appropriate backend microservice. You do not need to know individual service ports -- all requests go through the gateway at /api/v1/*.

API Endpoint Categories

Authentication & Authorization

Auth Service (port 9001)

JWT-based authentication with token binding, role-based access control, and multi-tenant organization scoping.

POST /api/v1/auth/loginPOST /api/v1/auth/refreshPOST /api/v1/auth/logoutGET /api/v1/auth/me

User Management

User Service (port 9002)

CRUD operations for users across all roles -- students, teachers, parents, and administrators.

GET /api/v1/usersPOST /api/v1/usersPUT /api/v1/users/:idGET /api/v1/users/:id/roles

Learning & Curriculum

Learning Service (port 9003)

Curriculum subjects, courses, topics, class management, timetabling, and session tracking.

GET /api/v1/learning/curriculum-subjectsGET /api/v1/learning/coursesGET /api/v1/learning/classesPOST /api/v1/learning/timetable-slots

Academic Calendar

Learning Service (port 9003)

Academic years, periods, calendar events, and scheduling across organizations.

GET /api/v1/academic-yearsGET /api/v1/academic-periodsGET /api/v1/calendar-eventsPOST /api/v1/calendar-events

Messaging

Communication Service (port 9005)

Multi-channel messaging with email, SMS, push, and in-app delivery. Includes acknowledgment tracking.

GET /api/v1/messages/inboxPOST /api/v1/messagesPUT /api/v1/messages/:id/readPOST /api/v1/messages/:id/acknowledge

Documents & Materials

Document Service (port 9006)

Document generation, publishing, and material sharing between teachers and students.

GET /api/v1/documentsPOST /api/v1/documentsGET /api/v1/learning/student/me/materialsPOST /api/v1/documents/:id/publish

Quick Start: Authentication

1. Obtain a token

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

{
  "email": "[email protected]",
  "password": "your_password"
}

2. Include token in requests

GET /api/v1/learning/classes
Authorization: Bearer <access_token>
X-Organization-ID: <organization_id>
Content-Type: application/json

3. Refresh when expired

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "<refresh_token>"
}

Additional Integration Options

Webhooks

In Development

Real-time event notifications for enrollment changes, grade updates, attendance events, and message delivery. Configure webhook endpoints per organization with retry policies and event filtering.

OAuth 2.0

In Development

Third-party application authentication using OAuth 2.0 authorization code flow. Register applications, define scopes, and allow users to grant access to their ScholarSync data securely.

Interactive API Documentation

Each backend service exposes auto-generated Swagger/OpenAPI documentation when running in development mode.

API Gateway:9000/docsAuth Service:9001/docsUser Service:9002/docsLearning Service:9003/docsAnalytics Service:9004/docsCommunication Service:9005/docs