Users API Documentation

Table of Contents

Retrieving a List of Users
Retrieving a User's Avatar
Creating a User
Modifying profile fields of the User
Modifying password of the User
Modifying admin role of the User
Modifying status of the User
Related API

GET /api/v1/users

Purpose

Retrieves a list of users from the server.

Authentication

Required: Secure, HTTP-only session cookie (or valid session token)
Unauthorized access returns a 401 error.

Request

Method: GET
URL: /api/v1/users
Headers: None required
Cookies: Valid session cookie must be present

Response

Success (200 OK)

JSON response example:

{
  "httpStatusCode": 200,
  "users": [
    {
      "createdUtc": 1718454147233,
      "displayName": "Admin",
      "isAdmin": true,
      "lastModifiedUtc": 1718454147233,
      "status": "Active",
      "userId": 1,
      "userName": "admin"
    },
    {
      "createdUtc": 1718454147239,
      "displayName": "Bob (Test User)",
      "isAdmin": false,
      "lastModifiedUtc": 1718454147239,
      "status": "Active",
      "userId": 2,
      "userName": "bob"
    }
  ]
}

Explanation:

userId: Unique identifier for the user
userName: System username
displayName: Name shown in the UI
isAdmin: true if the user is an administrator
status: Account status
- Possible values:
  - Active
  - Suspended
  - DeletionInProgress
createdUtc, lastModifiedUtc: Unix timestamps in milliseconds (UTC)

Error (any HTTP error code)

JSON response example:

{
    "errorText": "Wrong Bearer, please renew Web API Access Token",
    "httpStatusCode": 401
}

Explanation:

errorText: Contains a description of the failure
httpStatusCode: HTTP status code reflects the error type (e.g., 401 for unauthorized, 500 for internal error)

POST /api/v1/users

Purpose

Create a new user on the server.

Authentication

Required: Secure, HTTP-only session cookie (or valid session token)
Unauthorized access returns a 401 error.

Request

Method: POST
URL: /api/v1/users
Headers:
- Content-Type: application/json
Cookies: Valid session cookie must be present

Request Body

JSON object containing the message details:

{
  "userName": "John",
  "password": "123"
}

Explanation:

userName: System unique username of the new user.
password: Password of the new user.

Response

Success (200 OK)

JSON response example:

{
  "httpStatusCode": 200,
  "createdUser": {
      "createdUtc": 1718454147233,
      "displayName": "",
      "isAdmin": false,
      "lastModifiedUtc": 1718454147233,
      "status": "Active",
      "userId": 1,
      "userName": "John"
  }
}

Explanation:

userId: Unique identifier for the user
userName: System username
displayName: Name shown in the UI
isAdmin: true if the user is an administrator
status: Account status
- Possible values:
  - Active
  - Suspended
  - DeletionInProgress
createdUtc, lastModifiedUtc: Unix timestamps in milliseconds (UTC)

Error (any HTTP error code)

JSON response example:

{
    "errorText": "Wrong Bearer, please renew Web API Access Token",
    "httpStatusCode": 401
}

Explanation:

errorText: Contains a description of the failure
httpStatusCode: HTTP status code reflects the error type (e.g., 401 for unauthorized, 500 for internal error)

PUT /api/v1/users/${userId}/profile-fields

Purpose

Modify profile fields of the specified user.

Authentication

Required: Secure, HTTP-only session cookie (or valid session token)
Unauthorized access returns a 401 error.

Request

Method: PUT
URL Format: /api/v1/users/${userId}/profile-fields
- userId: The unique identifier of the user.
Headers:
- Content-Type: application/json
Cookies: Valid session cookie must be present

Request Body

JSON object containing the message details:

{
  "title": "",
  "firstName": "John",
  "middleName": "",
  "lastName": "Doe",
  "nickname": "JD",
  "dateOfBirthInJulianDay": 2442414,
  "jobTitle": "CEO",
  "jobDepartment": "Marketing Department",
  "jobDescription": "",
  "phoneNumbers": ["+1", "+49"],
  "emailAddresses": ["jdoe@company.com", "jdoe@gmail.com"],
  "socialProfileUrls": ["", ""],
  "postalAddresses": ["", ""]
}

Explanation:

title: Title of the user.
firstName: First name of the user.
middleName: Middle name of the user.
lastName: Last name of the user.
nickname: Nickname of the user.
dateOfBirthInJulianDay: Date of birth of the user in Julian day integer format.
jobTitle: Job title of the user.
jobDepartment: Job department of the user.
jobDescription: Job description of the user.
phoneNumbers: Array of phone numbers of the user.
emailAddresses: Array of email addresses of the user.
socialProfileUrls: Array of social profile URLs of the user.
postalAddresses: Array of postal addresses of the user.

Response

Success (200 OK)

JSON response example:

{
  "httpStatusCode": 200
}

Error (any HTTP error code)

JSON response example:

{
    "errorText": "Wrong Bearer, please renew Web API Access Token",
    "httpStatusCode": 401
}

Explanation:

errorText: Contains a description of the failure
httpStatusCode: HTTP status code reflects the error type (e.g., 401 for unauthorized, 500 for internal error)

PUT /api/v1/users/${userId}/password

Purpose

Modify password of the specified user.

Authentication

Required: Secure, HTTP-only session cookie (or valid session token)
Unauthorized access returns a 401 error.

Request

Method: PUT
URL Format: /api/v1/users/${userId}/password
- userId: The unique identifier of the user.
Headers:
- Content-Type: application/json
Cookies: Valid session cookie must be present

Request Body

JSON object containing the message details:

{
  "currentPassword": "123",
  "newPassword": "qwe",
}

Explanation:

currentPassword: Current password of the user. Optional field in the case of admin session.
newPassword: New password of the user.

Response

Success (200 OK)

JSON response example:

{
  "httpStatusCode": 200
}

Error (any HTTP error code)

JSON response example:

{
    "errorText": "Wrong Bearer, please renew Web API Access Token",
    "httpStatusCode": 401
}

Explanation:

errorText: Contains a description of the failure
httpStatusCode: HTTP status code reflects the error type (e.g., 401 for unauthorized, 500 for internal error)

PUT /api/v1/users/${userId}/admin-role

Purpose

Modify admin role of the specified user.

Authentication

Required: Secure, HTTP-only session cookie (or valid session token)
Unauthorized access returns a 401 error.

Request

Method: PUT
URL Format: /api/v1/users/${userId}/admin-role
- userId: The unique identifier of the user.
Headers:
- Content-Type: application/json
Cookies: Valid session cookie must be present

Request Body

JSON object containing the message details:

{
  "isAdmin": true
}

Explanation:

isAdmin: Admin role flag of the user. Must be true or false.

Response

Success (200 OK)

JSON response example:

{
  "httpStatusCode": 200
}

Error (any HTTP error code)

JSON response example:

{
    "errorText": "Wrong Bearer, please renew Web API Access Token",
    "httpStatusCode": 401
}

Explanation:

errorText: Contains a description of the failure
httpStatusCode: HTTP status code reflects the error type (e.g., 401 for unauthorized, 500 for internal error)

PUT /api/v1/users/${userId}/status

Purpose

Modify status of the specified user.

Authentication

Required: Secure, HTTP-only session cookie (or valid session token)
Unauthorized access returns a 401 error.

Request

Method: PUT
URL Format: /api/v1/users/${userId}/status
- userId: The unique identifier of the user.
Headers:
- Content-Type: application/json
Cookies: Valid session cookie must be present

Request Body

JSON object containing the message details:

{
  "status": 1
}

Explanation:

status: Account status
- Possible values:
  - 1 - Active
  - 2 - Suspended
  - 3 - DeletionInProgress

Response

Success (200 OK)

JSON response example:

{
  "httpStatusCode": 200
}

Error (any HTTP error code)

JSON response example:

{
    "errorText": "Wrong Bearer, please renew Web API Access Token",
    "httpStatusCode": 401
}

Explanation:

errorText: Contains a description of the failure
httpStatusCode: HTTP status code reflects the error type (e.g., 401 for unauthorized, 500 for internal error)

GET /api/v1/users/${userId}/avatar.jpg

Purpose

Retrieves the avatar image for a specific user.

Authentication

Required: Secure, HTTP-only session cookie (or valid session token)
Unauthorized access returns a 401 error.

Request

Method: GET
URL Format: /api/v1/users/${userId}/avatar.jpg
- userId: The unique identifier of the user whose avatar is being requested.
Headers: None required
Cookies: Must include a valid session cookie

Response

Success (200 OK)

Binary data of the user's avatar image.
The Content-Length header will indicate the size of the image.
The Content-Type header will reflect the MIME type of the image.
The Content-Disposition header will suggest the original filename for download.

Error (any HTTP error code)

JSON response example:

{
    "errorText": "Wrong Bearer, please renew Web API Access Token",
    "httpStatusCode": 401
}

Explanation:

errorText: Contains a description of the failure
httpStatusCode: HTTP status code reflects the error type (e.g., 401 for unauthorized, 500 for internal error)

Related API

Permissions API - retrieve user permissions
Status API - check current login state

All available Web API calls

Authentication with token – suitable for individual requests
Authentication with a username and password – suitable for maintaining a session to send multiple requests
Login with username and password – suitable for individual requests
Logout the current user – terminate the current session
Getting user status – check the current user's authentication and session status
Users API – retrieve user information
Rooms API – retrieve room information
Messages API – retrieve and send messages
Comments API – retrieve and send comments on messages
Attachments API – manage message attachments
Events API – receive real-time updates about changes on the server
Permissions API – retrieve user permissions in rooms
Server Health API – check the health status of the Virola Server