notifications-api/docs/adrs/0003-implementing-invite-expirations.md

# TITLE:  Implementing User Invite Expirations


| CREATED DATE | LAST UPDATED | STATUS | AUTHOR | STAKEHOLDERS |
| :---: | :---: | :---: | :---: | :---: |
| 06/06/2023 | 06/15/2023 | Proposed | @ccostino | @GSA/notify-contributors |


## CONTEXT AND PROBLEM STATEMENT

**OPEN ISSUE(S):** https://github.com/GSA/notifications-admin/issues/96

We've run into a situation where we want to re-invite users when their previous
invites have expired.  However, we're not currently able to do that because
there is no mechanism in the app (specifically the API and the data model) to
support expired invites.

Right now, users who are invited to the system receive an email invitation that
includes a note that the invitation will expire after 24 hours.

However, on the backend side of things, no such expiration exists.  Instead,
there is a scheduled job that runs every 66 minutes to check for all
`InvitedUser` objects that are older than 2 days and deletes them.

([Issue #96 in `notifications-admin`](https://github.com/GSA/notifications-admin/issues/96)
has more specific details.)


## DECISION DRIVERS

We'd like to adjust the API and data model so that invited users are no longer
deleted from the system and are instead tracked as active or expired.  When an
invite is expired, we'd like to be able to re-invite the person.


### SECURITY COMPLIANCE CONSIDERATIONS

The system currently has a data model for capturing an invited user
(`InvitedUser`), which is based on an authorized user of the system having the
permission to invite others to it.

These changes should not deviate from the existing structures and contraints
that are already in place, which prevent the following:

- Unauthorized users from accessing the system
- Users without the proper permissions from inviting others


## CONSIDERED OPTIONS

These are the different approaches we're considering for implementing this
change:

- **Adjust `InvitedUser` management in the API:**  Instead of deleting
  `InvitedUser` objects, we manage them instead and track their `created_at`
  dates for when they need to expire.  This would involve the following
  potential changes:

  - Add an `expired` flag to the `InvitedUser` model

  - Change the `delete_invitations` scheduled job to `expire_invitations` and
    change its behavior to check for `InvitedUser` objects that are older than
    24 hours and flip the `expired` flag to `True`.

  - Add an additional `INVITE_EXPIRED` status to the API and include it in the
    `INVITED_USER_STATUS_TYPES` enum.  This will be necessary for future UI
    changes.

  - Make sure the API responses that provided `InvitedUser` objects/data
    included the new `expired` field and status.

  - Update all tests related to `InvitedUsers` to account for the new behavior.

  The pros in making this change:

  - This will enable us to support expiring invites in the system, including
    frontend changes to enable seeing and managing expired invites.

  The cons in making this change:

  - Updated the tests might be a bit challenging depending on how many there are
    (especially any related to scheduled jobs).


## PROPOSED OPTION:  Adjust `InvitedUser` management in the API

I am proposing we adjust the `InvitedUser` management in the API and get these
updates in place first for future UI changes, because without them we cannot
display any expired invites nor offer a way of managing them or providing an
option to re-invite folks.

After looking through the code and researching how the existing user invite
flow works, these changes seem straight-forward and would yield us a lot of
value for the effort.


### Consequences

- Positive
  - Allows us to support expired invites
  - We could allow for custom expiration periods (either now or in the future)
  - Provides the mechanisms needed in the frontend to display and manage
    expired invites

- Negative
  - We might end up having to adjust a lot of tests; that's currently unclear.


## VALIDATION AND NEXT STEPS

TBD, pending additional ideas and discussion!

Once a decision is made though, a seperate issue should be written up for the
API changes that need to take place, and then follow-on work will be needed on
the admin side in https://github.com/GSA/notifications-admin/issues/96 to make
the UI adjustments.