Endpoints

All endpoints here are relative to the path the app’s URLs are included under.

Registering a New User

Once a user has submitted the registration form successfully, they will receive an email to verify their email address.

Due to privacy concerns related to exposing email addresses, a registration request with an email that is already in use will not fail. Instead it will send an email to the previously registered address notifying them of the registration attempt.

POST /register/
Request JSON Object:

  • <User.USERNAME_FIELD> (string) – The user’s username.

  • email (string) – The user’s email address.

  • password (string) – The user’s password.

Response JSON Object:

  • <User.USERNAME_FIELD> (string) – The username the user was created with.

  • email (string) – The email address the verification email was sent to.

Status Codes:

  • 201 Created – The request was successful and an email has been sent to the provded address.

  • 400 Bad Request – An invalid request was made. Check the response data for details.

Resending a Verification Email

If a user lost the original verification email or it has expired, this endpoint can be used to send a new verification.

In order to avoid exposing email addresses, submitting an email to this endpoint that is not in the database will appear to be a successful request but is actually a no-op.

POST /resend-verification/
Request JSON Object:

  • email (string) – The address to resend a verification email to.

Response JSON Object:

  • email (string) – The address the new verification email was sent to.

Status Codes:

  • 200 OK – The request was succesful.

  • 400 Bad Request – An invalid request was made. Check the response data for details.

Verify an Email Address

After a user receives a verification key, this endpoint is used to verify the email address.

POST /verify-email/
Request JSON Object:

  • key (string) – The verification key the user received.

  • password (string) – The user’s password. This field is only required if EMAIL_VERIFICATION_PASSWORD_REQUIRED is set to True.

Response JSON Object:

  • email (string) – The email address that was verified.

Status Codes:

  • 200 OK – The returned email was successfully verified.

  • 400 Bad Request – An invalid request was made. Check the response data for details.

Listing or Creating Email Addresses

All the email addresses associated with a user can be listed using the following endpoint. This endpoint can also be used to add a new email address to the user’s account.

GET /emails/

List the email addresses associated with the requesting user.

Response JSON Array of Objects:

  • id (int) – The ID that uniquely identifies the email address.

  • created_at (string) – A timestamp identifying when the email address was added by the user.

  • email (string) – The email’s actual address.

  • is_primary (boolean) – A boolean indicating if the address is the user’s primary address.

  • is_verified (boolean) – A boolean indicating if the email address has been verified.

POST /emails/

Add a new email address for the requesting user.

Request JSON Object:

  • email (string) – The address of the email to add.

Response JSON Object:

  • id (int) – The ID that uniquely identifies the email address.

  • created_at (string) – A timestamp identifying when the email address was added by the user.

  • email (string) – The email’s actual address.

  • is_primary (boolean) – A boolean indicating if the address is the user’s primary address.

  • is_verified (boolean) – A boolean indicating if the email address has been verified.

Viewing, Modifying, or Deleting a Specific Email Address

GET /emails/(int: id)/

Retrieve information about a specific email address.

Parameters:

  • id (int) – The unique ID of the email address to retrieve.

Response JSON Object:

  • id (int) – The ID that uniquely identifies the email address.

  • created_at (string) – A timestamp identifying when the email address was added by the user.

  • email (string) – The email’s actual address.

  • is_primary (boolean) – A boolean indicating if the address is the user’s primary address.

  • is_verified (boolean) – A boolean indicating if the email address has been verified.

Status Codes:

  • 200 OK – The email address was successfully retrieved.

  • 404 Not Found – There is no email address with the provided id accessible to the requesting user.

PUT /emails/(int: id)/

Update a specific email address.

Parameters:

  • id (int) – The unique ID of the email address to retrieve.

Request JSON Object:

  • email (string) – The original email address. This field may not be changed.

  • is_primary (boolean) – A boolean indicating if this address should be the user’s primary email. This may only be true for a verified email.

Response JSON Object:

  • id (int) – The ID that uniquely identifies the email address.

  • created_at (string) – A timestamp identifying when the email address was added by the user.

  • email (string) – The email’s actual address.

  • is_primary (boolean) – A boolean indicating if the address is the user’s primary address.

  • is_verified (boolean) – A boolean indicating if the email address has been verified.

Status Codes:

  • 200 OK – The email address was successfully updated.

  • 404 Not Found – There is no email address with the provided id accessible to the requesting user.

PATCH /emails/(int: id)/

Partially update a specific email address.

Parameters:

  • id (int) – The unique ID of the email address to retrieve.

Request JSON Object:

  • email (string) – (Optional) The original email address. This field may not be changed.

  • is_primary (boolean) – (Optional) A boolean indicating if this address should be the user’s primary email. This may only be true for a verified email.

Response JSON Object:

  • id (int) – The ID that uniquely identifies the email address.

  • created_at (string) – A timestamp identifying when the email address was added by the user.

  • email (string) – The email’s actual address.

  • is_primary (boolean) – A boolean indicating if the address is the user’s primary address.

  • is_verified (boolean) – A boolean indicating if the email address has been verified.

Status Codes:

  • 200 OK – The email address was successfully updated.

  • 404 Not Found – There is no email address with the provided id accessible to the requesting user.

DELETE /emails/(int: id)/

Delete the email address with the specified id.

Parameters:

  • id (int) – The unique ID of the email address to delete.

Status Codes:

  • 204 No Content – The email address was successfully deleted.

  • 404 Not Found – There is no email address with the provided id accessible to the requesting user.

Password Resets

Users may request a password reset using any of their verified emails.

Request a Reset

Sending a request to this endpoint will email the user a link that they can use to reset their password.

POST /request-password-reset/

Request a new password reset.

Request JSON Object:

  • email (string) – The email address to send the reset token to.

Status Codes:

  • 200 OK – This status is always returned to avoid leaking information about which emails exist in the system.

Reseting a Password

After the user receives an email address with a token they can use to reset their password, this endpoint should be used.

POST /reset-password/

Reset the user’s password.

Request JSON Object:

  • key (string) – The token that the user was emailed authorizing the reset.

  • password (string) – The user’s new password.

Status Codes:

  • 200 OK – The user’s password was reset successfully.

  • 400 Bad Request – Either the provided key does not exist or has expired, or the provided password is invalid.