.. SPDX-License-Identifier: GPL-3.0-or-later

====================================
Authentication and user accounts API
====================================

1. Login
========

WeChat Mini Program login:

.. code:: bash

   POST /api/v1/auth/login/wechat

Body:

.. code:: json

   {
     "code": "temporary login credential returned by Mini Program wx.login()",
     "totp_code": "123456"
   }

Notes:

-  The backend exchanges ``code`` with the WeChat server for an
   ``openid``, then finds the user bound to that ``openid``.
-  Mini Programs do not support cookies. Tokens are returned directly in
   the response body, and the Mini Program must store them itself.
-  ``totp_code`` is required when the account has TOTP enabled.

Email, student ID, or staff ID plus password login:

.. code:: bash

   POST /api/v1/auth/login/email

Body:

.. code:: text

   {
     "email": "teacher@school.edu",
     "password": "your_password",
     "totp_code": "123456"
   }

Notes:

-  ``email`` accepts either an email address or ``user_code``.
-  ``totp_code`` is required when the account has TOTP enabled.
-  Accounts with TOTP enabled must also include ``totp_code`` in the
   request body when using WeChat login.

1.1 Two-factor authentication (TOTP)
------------------------------------

Set up a time-based one-time password for the account:

.. code:: bash

   POST /api/v1/auth/totp/setup

Example response:

.. code:: json

   {
     "code": 0,
     "message": "success",
     "data": {
       "secret": "BASE32SECRET",
       "provisioning_uri": "otpauth://totp/Classroom%20Manager:tester%40school.edu?..."
     }
   }

After scanning the QR code, submit the verification code to enable TOTP:

.. code:: bash

   POST /api/v1/auth/totp/enable

Body:

.. code:: json

   {
     "totp_code": "123456"
   }

1.2 Passwordless login (WebAuthn)
---------------------------------

The system supports WebAuthn authentication with security keys and
platform devices. The flow has two steps: key registration and login.
All endpoints follow the unified ``success/error`` response structure.

Register a security key (authenticated)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Request registration options. Pass optional ``device_name`` to label
   the device.

.. code:: bash

   POST /api/v1/auth/webauthn/options/register

The response contains the ``publicKey`` options required by browser
``navigator.credentials.create``.

2. Submit the credential generated by the browser.

.. code:: bash

   POST /api/v1/auth/webauthn/register

Example body:

.. code:: text

   {
     "credential": { ... },
     "device_name": "MacBook Touch ID"
   }

Login with a security key (anonymous)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Request login options.

.. code:: bash

   POST /api/v1/auth/webauthn/options/login

Body:

.. code:: json

   { "identifier": "teacher@school.edu" }

2. Submit the authentication result to obtain a JWT.

.. code:: bash

   POST /api/v1/auth/webauthn/login

Body:

.. code:: text

   { "credential": { ... } }

Disable TOTP authentication:

.. code:: bash

   POST /api/v1/auth/totp/disable

Body:

.. code:: json

   {
     "totp_code": "123456"
   }

If TOTP is currently enabled, the verification code is required to
confirm the change.

2. Invite a foreign teacher to register (admin)
===============================================

.. code:: bash

   POST /api/v1/users/invite-foreign

Body:

.. code:: json

   {
     "email": "teacher@school.edu",
     "full_name": "John Smith"
   }

3. Email registration (foreign teacher)
=======================================

.. code:: bash

   POST /api/v1/auth/register/email

Body:

.. code:: json

   {
     "email": "teacher@school.edu",
     "password": "12345678",
     "full_name": "John Smith"
   }

Notes:

-  The user is logged in automatically after successful registration.
-  The default role for the new user is ``foreign_teacher``.

4. Get current user information
===============================

.. code:: bash

   GET /api/v1/auth/me

5. User list (admin)
====================

.. code:: bash

   GET /api/v1/users

Query:

-  ``role`` (optional)
-  ``status`` (optional)
-  ``search`` (optional; matches name, student ID, or staff ID)
-  ``page``, ``page_size`` (also supports ``size``)

6. Create user (superadmin / secretary)
=======================================

.. code:: bash

   POST /api/v1/users

Body:

.. code:: json

   {
     "user_code": "2024123456",
     "username": "johnsmith",
     "full_name": "John Smith",
     "email": "johnsmith@school.edu",
     "roles": ["student"],
     "password": "optional_password"
   }

Notes:

-  If no password is provided, the default password is
   ``defaultPass123``.

7. Update user information (superadmin / secretary)
===================================================

.. code:: bash

   PUT /api/v1/users/{id}

8. Change role (superadmin)
===========================

.. code:: bash

   PUT /api/v1/users/{id}/role

Body:

.. code:: json

   { "role": "assistant" }

9. Disable or enable account (superadmin / secretary)
=====================================================

.. code:: bash

   PUT /api/v1/users/{id}/status

Body:

.. code:: json

   { "status": "active" }

10. Import users from Excel (superadmin / secretary)
====================================================

.. code:: bash

   POST /api/v1/users/import
   Content-Type: multipart/form-data

Fields:

-  ``file``: Excel file.

Header conventions:

-  Required: student ID, staff ID, ``user_code``, or combined
   student/staff ID column; and name or ``full_name``.
-  Optional: username or ``username``, email or ``email``, role or
   ``role``.
-  If username is empty, the backend falls back to ``user_code``.
-  If role is empty, the backend defaults to ``student``.
-  The template no longer contains a ``password`` column. Even if an
   Excel file contains that column, the backend does not import it as
   the login password.

Import strategy:

-  Backend ``user_code`` is used as the unique key. Existing users are
   skipped and not overwritten.
-  Newly imported users are created with ``active`` status, and Django
   ``set_unusable_password()`` is called to set an unusable password.
-  To enable password login, an administrator must set a password
   separately through the user edit API after import.

11. Refresh token
=================

.. code:: bash

   POST /api/v1/auth/token/refresh

Body for Mini Program clients:

.. code:: json

   {
     "refresh": "refresh_token_here"
   }

Notes:

-  Web: ``refresh_token`` is read automatically from the HttpOnly
   cookie.
-  Mini Program: provide ``refresh`` or ``refresh_token`` in the request
   body.

12. Logout
==========

.. code:: bash

   POST /api/v1/auth/logout

Notes:

-  Clears authentication cookies for web clients.

13. Bind Weixin/WeChat
======================

Bind the current logged-in user to a WeChat ``openid``. After binding,
the user can log in with one tap through WeChat.

.. code:: bash

   POST /api/v1/auth/wechat/bind

Body:

.. code:: json

   {
     "code": "temporary login credential returned by Mini Program wx.login()"
   }

Permission: login required.

14. Unbind Weixin/WeChat
========================

Remove the binding between the current user and WeChat.

.. code:: bash

   POST /api/v1/auth/wechat/unbind

Permission: login required.

15. Get SM2 public key
======================

Used by the frontend to encrypt sensitive data, such as passwords in
transit.

.. code:: bash

   GET /api/v1/accounts/sm2/public-key

Permission: no login required.

Response:

.. code:: json

   {
     "code": 0,
     "message": "success",
     "data": {
       "public_key": "SM2 public key string",
       "fingerprint": "public key fingerprint"
     }
   }