[Documentation] Need to Add/Alter API Endpoint Instructions, etc. to Reflect New Auth Flow

[BethanyG]

Now that we'e decided to implement a Registration and Login flow and re-organize our auth endpoints (PR #187), post-merge we'll need to update our documentation to show the endpoint & functionality changes:

1. Registration will now require an email
2. A user will not be able to sign in without a validated email
3. Email addresses are validated through an email with a special link containing a token. The token needs to be passed in a POST to the api/v1/auth/verify-email/ endpoint, which will flag the email as "valid" in the DB.
4. Users will also be able to request password reset emails. Password reset emails will contain a UID and TOKEN. A POST to /api/v1/auth/password/reset/confirm/ with:

{
    "new_password1": "",
    "new_password2": "",
    "uid": "",
    "token": ""
}

will reset the user password associated with the UID.

---

Current Endpoints after PR #187 is merged:

Django Admin Interface and Login:

• /admin/ (to login to the admin interface with superuser credentials)

Obtaining JWT tokens:

• api/v1/auth/token (obtain an access & refresh token pair),
• api/v1/auth/verify (verify the validity of a refresh or access token),
• api/v1/refresh (obtain new access toke by using non-expired refresh token)

The length of time access and refresh tokens remain valid can be configured in config/settings/base.py by adding a SIMPLE_JWT={} dictionary of values. please note: this project does not currently use SLIDING_TOKEN, only ACCESS_TOKEN and REFRESH_TOKEN current defaults from the library are:

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=5),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
    'ROTATE_REFRESH_TOKENS': False,
    'BLACKLIST_AFTER_ROTATION': True,

    'ALGORITHM': 'HS256',
    'SIGNING_KEY': settings.SECRET_KEY,
    'VERIFYING_KEY': None,
    'AUDIENCE': None,
    'ISSUER': None,

    'AUTH_HEADER_TYPES': ('Bearer',),
    'USER_ID_FIELD': 'id',
    'USER_ID_CLAIM': 'user_id',

    'AUTH_TOKEN_CLASSES': ('rest_framework_simplejwt.tokens.AccessToken',),
    'TOKEN_TYPE_CLAIM': 'token_type',

    'JTI_CLAIM': 'jti',

    'SLIDING_TOKEN_REFRESH_EXP_CLAIM': 'refresh_exp',
    'SLIDING_TOKEN_LIFETIME': timedelta(minutes=5),
    'SLIDING_TOKEN_REFRESH_LIFETIME': timedelta(days=1),
}

Registration/Login/Logout/password reset:

• api/v1/auth/registration/ (on submit, triggers a validation email to the email address a user enters)
• api/v1/auth/verify-email/ (POST a user's HMC email key for validating their email)
• api/v1/auth/login/ (Requires a validated email in order to sign in)
• api/v1/auth/logout/ (Clear tokens from currently logged in user)
• api/v1/auth/password/reset/ (if POST-ed to with an email, will send a password reset email to the POSTED email)
• api/v1/auth/password/reset/confirm/ (if POST-ed to with the UID & TOKEN from the reset email & new password, will reset the password for the UID POSTED)

User Details & current_user:

• api/v1/auth/user/ (to view currently logged in User Details)
• api/v1/auth/current_user (to view currently logged in User minus their email address)

Viewing and Creating Resources:

• api/v1/resources/ (GET view a list of resources available. No auth required.)
• api/v1/resources/ (POST view to create a resource. Requires a valid access or refresh token.)
• api/v1/resources/ (PATCH view to edit/update a resource. Requires a valid access or refresh token.)

---

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[BethanyG]

Still open.