Account¶

KMUser¶

A user’s know me user contains personal information about the user such as their email or name.

Note

If you are looking to change a user’s password, see the Change Password endpoint.

GET /account/profile/¶

Retrieve the requesting user’s account information.

Response JSON Object:
	id (int) – The user’s ID. email (string) – The user’s email address. first_name (string) – The user’s first name. last_name (string) – The user’s last name.
Status Codes:	200 OK – The user’s information was successfully retrieved.

PATCH /account/profile/¶

Update the requesting user’s information.

Request JSON Object:
	first_name (string) – (Optional) The user’s new first name. last_name (string) – (Optional) The user’s new last name.
Response JSON Object:
	id (int) – The user’s ID. email (string) – The user’s email address. first_name (string) – The user’s first name. last_name (string) – The user’s last name.
Status Codes:	200 OK – The user’s information was successfully updated. 400 Bad Request – Invalid request. Check the response data for details.

Change Password¶

POST /account/change-password/¶

Change the password of the currently authenticated user.

Request JSON Object:
	key (string) – (Optional) The password reset key authorizing a password change. The key can be obtained from the password reset view. Either this field or `old_password` must be given. old_password (string) – (Optional) The user’s current password. Either this field or `key` must be given. new_password (string) – The user’s new password.
Status Codes:	200 OK – The user’s password was successfully changed. 400 Bad Request – Invalid request. Check response data for details. This can happen when an invalid `old_password` is provided, or if `new_password` fails the password validation checks.

Reset Password¶

If a user forgets their password, sending their email address to this endpoint will send them an email with instructions to reset their password.

Warning

Just because a 200 OK response was received does not mean that the provided email address was valid. We can’t return any information about the validity of the email without giving away information about which accounts exist.

POST /account/reset-password/¶

Request a password reset for the account associated with the provided email address.

Request JSON Object:
	email (string) – The email address to send a password reset email to.
Response JSON Object:
	email (string) – The email address that the password reset was sent to.
Status Codes:	200 OK – A valid email address was received. 400 Bad Request – An invalid email address was received.

Email Verification¶

Before a user can log in, they must have a verified email address. This allows us to contact the user with any account related messages.

Note

We require the user’s password to prevent mistyped email addresses from being verified by an unknown user. See #39 for details.

POST /account/verify-email/¶

Verify an email address.

Request JSON Object:
	key (string) – The confirmation key that was sent to the user’s email. password (string) – The user’s password.
Status Codes:	200 OK – The email address was confirmed. 400 Bad Request – Invalid request. Check the response data for details. This can happen if an invalid key was provided, or if the key has expired.

Email Management¶

Users are allowed to have multiple emails associated with their account. One of these emails is the user’s primary address, and receives all notifications. The user can log in with any of their verified emails.

Email List¶

The email list endpoint allows for listing of a user’s email addresses as well as adding new emails.

GET /account/emails/¶

List the requesting user’s email addresses.

Response JSON Array of Objects:

id (int) – The ID of the email address.
email (string) – The email’s address.
verified (boolean) – A boolean indicating if the address has been verified.
verified_action (int) – An integer corresponding to an action to perform when the email is verified. See Email Verification Actions for more information.
primary (boolean) – A boolean indicating if the address is the user’s primary email.

Status Codes:

200 OK – The user’s email addresses were successfully retrieved.

POST /account/emails/¶

Add a new email address for the requesting user.

Request JSON Object:
	email (string) – The address of the new email.
Response Headers:
	Location – The URL of the created email address’ detail view.
Response JSON Object:
	id (int) – The ID of the email address. url (string) – The URL of the email address’ detail view. email (string) – The email’s address. verified (boolean) – A boolean indicating if the address has been verified. verified_action (int) – An integer corresponding to an action to perform when the email is verified. See Email Verification Actions for more information. primary (boolean) – A boolean indicating if the address is the user’s primary email.
Status Codes:	201 Created – The email address was created successfully. 400 Bad Request – Invalid request. Check the response data for details.

Email Detail¶

The email detail endpoint allows for retrieving and updating a specific email address as well as removing email addresses.

GET /account/emails/(int: id)/¶

Get the details of a specific email address.

Response JSON Object:

id (int) – The ID of the email address.
url (string) – The URL of the email address’ detail view.
email (string) – The email’s address.
verified (boolean) – A boolean indicating if the address has been verified.
verified_action (int) – An integer corresponding to an action to perform when the email is verified. See Email Verification Actions for more information.
primary (boolean) – A boolean indicating if the address is the user’s primary email.

Status Codes:

200 OK – The email address’ details were successfully retrieved.
404 Not Found – There is no email address with the given id accessible to

the requesting user.

PATCH /account/emails/(int: id)/¶

Update the details of a specific email address.

Request JSON Object:
	primary (boolean) – (Optional) A boolean indicating if the specified email address should be the user’s new primary email.
Response JSON Object:
	id (int) – The ID of the email address. url (string) – The URL of the email address’ detail view. email (string) – The email’s address. verified (boolean) – A boolean indicating if the address has been verified. primary (boolean) – A boolean indicating if the address is the user’s primary email.
Status Codes:	200 OK – The email address’ details were successfully updated. 404 Not Found – There is no email address with the given `id` accessible to the requesting user.

DELETE /account/emails/(int: id)/¶

Delete a specific email address.

Status Codes:	204 No Content – The email address was successfully deleted. 404 Not Found – There is no email address with the given `id` accessible to the requesting user. 409 Conflict – The email address is the user’s primary address so it could not be deleted.

Email Verification Actions¶

When an email address is created, an action can be specified to control what happens when the email is verified. This endpoint provides a list of those actions.

GET /account/emails/actions/¶

Get a list of available verification actions.

Response JSON Array of Objects:
	id (int) – The action’s ID. label (string) – The action’s label.
Status Codes:	200 OK – The available actions were successfully retrieved.