Outdated API Documentation for User Authentication

[nus-pe-bot]

Bug Report: Outdated API Documentation for User Authentication

Summary

The API documentation for user authentication endpoints is outdated and does not reflect recent changes in the authentication process.

Description

Our API documentation, last updated on 2023-09-15, does not accurately describe the current user authentication process. Specifically:

1. The documented endpoint for user login (/api/v1/login) has been changed to (/api/v2/auth/login).
2. The required parameters for the login request have changed, but this is not reflected in the documentation.
3. The response structure for successful authentication has been modified to include additional user information.
4. New endpoints for multi-factor authentication are not documented at all.

Screenshot

Impact

• Developer Experience: Third-party developers and internal teams are unable to correctly implement or use our authentication system.
• Support Load: Increased number of support tickets related to authentication issues.
• Integration Failures: Partners attempting to integrate with our system are experiencing failures due to incorrect endpoint usage.

Correct Information

1. The current login endpoint is: POST /api/v2/auth/login
2. Required parameters now include:
   • username (string)
   • password (string)
   • device_id (string)
3. Successful response now includes:
   • token (string)
   • refresh_token (string)
   • user_id (integer)
   • roles (array of strings)
4. New MFA endpoints:
   • POST /api/v2/auth/mfa/initiate
   • POST /api/v2/auth/mfa/verify

Steps to Resolve

1. Update the API documentation to reflect the current authentication process.
2. Add a new section for Multi-Factor Authentication.
3. Include example requests and responses for each endpoint.
4. Add a changelog to the documentation to track future updates.
5. Implement a process for keeping documentation in sync with code changes.

Additional Notes

• Consider adding deprecation notices for the old endpoints, including a timeline for when they will be fully decommissioned.
• A notification should be sent to all registered API users about these documentation updates.

Severity

High - Incorrect documentation is directly impacting the ability of developers to integrate with our system.

Assigned To

Emily Chang (Technical Writer)

Priority

P1 - Critical documentation issue affecting core API functionality

---

Reporter: Michael Wong Date Reported: 2024-03-22

---

_{[original: CATcher-testbed/alpha10-interim#140] [original labels: type.DocumentationBug severity.High]}

[LamJiuFong]

Team's Response

No details provided by team.

Duplicate status (if any):

Duplicate of #11