Skip to main content
The Dzidzo SMS platform utilizes a dual-authentication strategy to cleanly separate global platform administration from tenant-specific school operations. Both strategies utilize JWT (JSON Web Tokens) for stateless, secure session management.

​
Authentication Layers

​
1. System Authentication (/api/v1/system/auth/)

This layer is strictly for Platform Administrators (e.g., developers, superusers, global support staff).
  • Target Audience: Users who do not belong to a specific school (their client field is null).
  • Behavior: If a user attempts to log into the system endpoints but is bound to a school, the API will explicitly reject them with a 403 Forbidden error.
  • Key Endpoints:
    • POST /api/v1/system/auth/login/: Authenticate and receive JWT pair.
    • GET /api/v1/system/auth/me/: Retrieve global profile data.

​
2. School Authentication (/api/v1/school/auth/)

This layer is for Tenant Users (e.g., teachers, principals, students) operating within a specifically provisioned school domain.
  • Target Audience: Users bound to a specific school (client field is set).
  • Behavior: You must issue these requests against the specific tenant’s subdomain (e.g., https://school_a.sms.local/api/v1/school/auth/login/). If a platform admin attempts to log in here, they will be rejected.
  • Context Injection: Upon successful login, the API automatically injects tenant-specific context into the response, including:
    • The user’s specific Roles within that school.
    • The user’s Teacher Profile (if they are assigned the Teacher role).
  • Key Endpoints:
    • POST /api/v1/school/auth/login/: Authenticate within the tenant.
    • GET /api/v1/school/auth/me/: Retrieve tenant-scoped profile.

​
Token Management

When you successfully authenticate, the API returns two tokens:
  1. access: Short-lived token included in the Authorization: Bearer <token> header for subsequent requests.
  2. refresh: Long-lived token used to obtain a new access token when it expires.

​
Refreshing Tokens

Instead of forcing users to log in again, use the refresh endpoint: 
POST /api/v1/school/auth/refresh/
Content-Type: application/json

{
  "refresh": "<your_refresh_token>"
}

​
Role-Based Access Control (RBAC)

The platform heavily utilizes custom permissions based on the roles assigned to a user within their tenant:
  • DynamicModelPermissions: The core API views intercept requests and verify if the user’s assigned roles permit the specific HTTP action (GET, POST, PUT, DELETE) on that resource.
  • Role Examples: IsSuperAdmin, IsPlatformAdmin, IsSchoolUser.
Cross-Tenant Isolation A JWT token generated for a user in School A is cryptographically valid, but if that token is used against School B’s subdomain, the database lookup strategy enforced by django-tenants will reject the context, ensuring data isolation.