Outdated API Documentation for User Authentication

[tim-pipi]

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

[nus-se-bot]

Team's Response

No details provided by team.

The 'Original' Bug

[The team marked this bug as a duplicate of the following bug]

Test issue with no description

No details provided by bug reporter.

---

_{[original: CATcher-testbed/alpha10-interim#16] [original labels: severity.Low type.FeatureFlaw]}

Their Response to the 'Original' Bug

[This is the team's response to the above 'original' bug]

No details provided by team.

Items for the Tester to Verify

:question: Issue duplicate status

Team chose to mark this issue as a duplicate of another issue (as explained in the Team's response above)

• [ ] I disagree

Reason for disagreement: [replace this with your explanation]

---

## :question: Issue response Team chose [`response.Rejected`] - [ ] I disagree **Reason for disagreement:** [replace this with your explanation]

---

## :question: Issue type Team chose [`type.FeatureFlaw`] Originally [`type.DocumentationBug`] - [ ] I disagree **Reason for disagreement:** [replace this with your explanation]

---

## :question: Issue severity Team chose [`severity.Low`] Originally [`severity.High`] - [ ] I disagree **Reason for disagreement:** [replace this with your explanation]

---