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.
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.