A collection of methods for managing users. Authentication can differ for each, pay attention to the headers. Request body is a JSON object, but placeholders for data types instead of concrete samples might be used like so: <UUID> or "…" for strings.
Registers and logs in a new user. Response will contain DeviceSession.accessToken which you should put to the request header.
Path:
POST /users
Request body:
{
"name": "…",
"username": "…",
"password": "…",
"deviceInfo": <DeviceInfo>,
"securityQuestion": "…",
"securityAnswer": "…"
}
On a server running with --env production, the password must be 8-25 characters and contain an uppercase letter, a lowercase letter and a digit; the same rules apply to every endpoint that sets a new password. A server running locally (development or testing environment) accepts any non-empty password.
securityQuestion and securityAnswer are optional, but if one is sent the other must be too. They are what password recovery checks. The answer is compared trimmed and case-insensitively.
Response: UserInfo object.
See also: DeviceInfo
Logs in user from a particular device. Response will contain DeviceSession.accessToken which you should put to the request header.
Path:
POST /users/login
Headers:
Authorization: Basic <username:password>
Request body:
{
"deviceInfo": <DeviceInfo>
}
Response: UserInfo object.
See also: DeviceInfo, DeviceSession
Gets all the information of the current user.
Path:
GET /users/me
Headers:
Authorization: Bearer <token>
Response: UserInfo object.
Logs out user and invalidates DeviceSession.accessToken.
Path:
POST /users/me/logout
Headers:
Authorization: Bearer <token>
Response: OK
See also: DeviceSession
Changes password for the user. Requires both DeviceSession.accessToken and the old password.
Path:
PUT /users/me/changePassword
Headers:
Authorization: Bearer <token>
Request body:
{
"oldPassword": "…",
"newPassword": "…"
}
Response: OK
Sets the account key which is necessary for restoration of the account in case of password loss.
Path:
PUT /users/me/setAccountKey
Headers:
Authorization: Bearer <token>
Request body:
{
"password": "…",
"accountKey": "…"
}
Response: OK
Resets user's password in case of a valid account key provided.
Path:
PUT /users/resetPassword
Request body:
{
"userId": <Int>,
"accountKey": "…",
"newPassword": "…"
}
Response: OK
Updates user's information, such as name and about.
Path:
PUT /users/me
Headers:
Authorization: Bearer <token>
Request body:
{
"name": "…",
"about": "…"
}
Response: OK
Updates user's device session information, such as deviceName and deviceToken.
Path:
PUT /users/me/device
Headers:
Authorization: Bearer <token>
Request body:
{
"deviceName": "…", // f.e. "My laptop"
"deviceToken": "…" // Push token (APNS or Android)
}
Response: OK
Gets all the public information about a user.
Path:
GET /users/<id>
Response: UserInfo object.
Looks for people by their name or username using substring.
Path:
GET /users/?s=foo
Response: an array of UserInfo objects.
Adds a photo to the current user. Media should be uploaded beforehand. See Files section.
Path:
POST /users/me/photos
Headers:
Authorization: Bearer <token>
Request body:
{
"photo": {
"id": <UUID>, // should be obtained beforehand by uploading a file
"fileType": "png",
"fileSize": 100000 // in bytes
}
}
Response: OK
Deletes the photo from the current user together with all the media.
Path:
DELETE /users/me/photos/<UUID>
Headers:
Authorization: Bearer <token>
Response: OK
Deletes user with all the associated data (created chats, messages, settings etc.). Can't be undone. Use with caution.
Path:
DELETE /users/me
Headers:
Authorization: Basic <username:password>
Response: OK
The first step of password recovery. Returns the security question of the account with the given username. An unknown username and an account without a question both return 404.
Path:
POST /users/recover/question
Request body:
{
"username": "…"
}
Response:
{
"question": "…"
}
The second step of password recovery. Sets a new password if the answer to the security question is correct, otherwise returns 403.
Path:
POST /users/recover/reset
Request body:
{
"username": "…",
"answer": "…",
"newPassword": "…"
}
Response: OK
Returns the current user's security question. question is omitted when none is set. The answer is never returned.
Path:
GET /users/me/security
Headers:
Authorization: Bearer <token>
Response:
{
"question": "…"
}
Sets a new security question and answer. Requires the current password, so a session alone cannot change how the account is recovered.
Path:
PUT /users/me/security
Headers:
Authorization: Bearer <token>
Request body:
{
"password": "…",
"securityQuestion": "…",
"securityAnswer": "…"
}
Response: OK