API: Users

This page will detail how to work with the User model. The User model is created when a user creates an account, which is covered under API: Authentication - Sign up.

Path

/api/users

Permissions

Only the signed in user can access or modify it. The only alternative is when a user needs to reset their forgotten password.

Fields

Field Name	Type	Required?	Default Value	Read Only?	Description
email	string	Yes		No	The user's email address which is specified during registration
first_name	string	No	''	No	The user's first name
last_name	string	No	''	No	The user's last name
password	string	Yes		No	The user's password, encrypted before saved
is_superuser	boolean	No	false	No	Flag that is used to determine if user has escalated permissions
date_joined	datetime	Yes		Yes	The time the object is created. It is auto-generated

Updating

To update a user's information, you can send a PATCH request to /api/users/update_details. There is no need to put any identifiers in the URL, all of that will go in the body. The user's current password is a required field in the request.

Required Fields

Name	Type	Description
current-password	string	The user's current password

Status Codes

200: The user was updated successfully

400: There were bad or missing values in the request body

Example Request

PATCH /api/users/update_details
Host: sanaprotocolbuilder.me
Authorization: Token <token>

{
    "current-password": "mypassword",
    "email": "[email protected]"
}

Example Response

{
    "id": 21,
    "is_superuser": false,
    "first_name": "John",
    "last_name": "Doe",
    "username": "jc123",
    "email": "[email protected]"
}

Get User

To get a user's details, you can send a GET request to /api/users/{id} where id is the current user's id.

Required Fields

Name	Type	Description
id	int	The user's id

Status Codes

200: Success

400: There were bad or missing values in the request body

404: User was not found

Example Request

GET /api/users/41
Host: sanaprotocolbuilder.me
Authorization: Token <token>

Example Response

{
    "id": 21,
    "is_superuser": false,
    "first_name": "John",
    "last_name": "Doe",
    "username": "jc123",
    "email": "[email protected]"
}

User - Password

Reset Password

To reset a user's password, there is a 2 step process. The first step is to send a POST request to /api/passwords/reset_password. The only field required is email.

Required Fields

Name	Type	Description
email	string	The user's email address used to register the account with

Status Codes

200: Successful request. The password reset link has been queued for email delivery.

400: Missing or invalid data in request body

404: No user with that email exists

Example Request

POST /api/passwords/reset_password
Host: sanaprotocolbuilder.me

{
    "email": "[email protected]"
}

Once this step has been completed, the user will receive a password reset link in an email. The link expires in 48 hours. In order to complete the password reset, send a POST request to /api/passwords/reset_password_complete.

Required Fields

Name	Type	Description
new_password	string	The user's new password
password_confirmation	string	The new password repeated
reset_token	string	The password reset token that is part of the URL the user used to access page

Status Codes

201: User's password token successfully created and queued for email 400: Missing or invalid data in request body. This could include mismatching password and password confirmations

Example Request

PATCH /api/passwords/reset_password_complete
Host: sanaprotocolbuilder.me

{
    "new_password": "newpass",
    "password_confirmation": "newpass",
    "reset_token": "49v-6bf384458f725125c0b7"
}