Users

Users API

The Users API provides endpoints to manage users, roles, and authentication in your PoloCloud instance.

Manage users, roles, authentication, and access control via REST API

Create User

Create a new user with a specific role (admin only).

Endpoint: POST /polocloud/api/v3/user/

Request Body:

{
  "username": "newuser",
  "roleId": 2
}

Response:

{
  "status": 201,
  "message": "User created successfully",
  "data": {
    "password": "generated-password-123"
  }
}

Error Responses:

400 - Username is required
404 - Role not found

Create Self User

Create the first admin user (only works when no users exist).

Endpoint: POST /polocloud/api/v3/user/self

Request Body:

{
  "username": "admin",
  "password": "your-secure-password",
  "roleId": -1
}

Response:

{
  "status": 201,
  "message": "User created successfully"
}

Error Responses:

400 - Username is required / Password is required / A user already exists

List Users

Retrieve all users (admin only).

Endpoint: GET /polocloud/api/v3/users/

Response:

{
  "status": 200,
  "data": [
    {
      "uuid": "03eec725-0975-424d-9633-b8b0883ecca7",
      "username": "admin",
      "role": {
        "id": -1,
        "label": "Admin",
        "hexColor": "#FF0000",
        "default": true,
        "permissions": ["*"]
      },
      "hasChangedPassword": true,
      "createdAt": 1757608221286
    }
  ]
}

Get User

Retrieve a specific user by UUID (admin only).

Endpoint: GET /polocloud/api/v3/user/{uuid}

Parameters:

uuid (path) - The UUID of the user to retrieve

Response:

{
  "status": 200,
  "data": {
    "uuid": "03eec725-0975-424d-9633-b8b0883ecca7",
    "username": "admin",
    "role": {
      "id": -1,
      "label": "Admin",
      "hexColor": "#FF0000",
      "default": true,
      "permissions": ["*"]
    },
    "hasChangedPassword": true,
    "createdAt": 1757608221286
  }
}

Error Responses:

404 - User not found

Get Self

Retrieve current user information.

Endpoint: GET /polocloud/api/v3/user/self

Response:

{
  "status": 200,
  "data": {
    "uuid": "03eec725-0975-424d-9633-b8b0883ecca7",
    "username": "admin",
    "role": {
      "id": -1,
      "label": "Admin",
      "hexColor": "#FF0000",
      "default": true,
      "permissions": ["*"]
    },
    "hasChangedPassword": true,
    "createdAt": 1757608221286
  }
}

Edit User

Update a user's role (admin only).

Endpoint: PATCH /polocloud/api/v3/user/edit

Request Body:

{
  "uuid": "03eec725-0975-424d-9633-b8b0883ecca7",
  "roleId": 2
}

Response:

{
  "status": 201,
  "message": "User updated"
}

Error Responses:

400 - UUID is required
403 - You cannot assign the admin role
404 - User not found

Edit Self

Update your own username.

Endpoint: PATCH /polocloud/api/v3/user/self/edit

Request Body:

{
  "username": "new-username"
}

Response:

{
  "status": 201,
  "message": "User updated"
}

Error Responses:

400 - Username is required

Change Password

Change your own password.

Endpoint: PATCH /polocloud/api/v3/user/self/change-password

Request Body:

{
  "password": "new-secure-password"
}

Response:

{
  "status": 200,
  "message": "Password changed successfully"
}

Error Responses:

400 - Password is required

Delete User

Delete a user by UUID (admin only).

Endpoint: DELETE /polocloud/api/v3/user/{uuid}

Parameters:

uuid (path) - The UUID of the user to delete

Response:

{
  "status": 204
}

Delete Self

Delete your own account.

Endpoint: DELETE /polocloud/api/v3/user/self

Response:

{
  "status": 204
}

Token Management

List Tokens

Get all your authentication tokens.

Endpoint: GET /polocloud/api/v3/user/tokens

Response:

{
  "status": 200,
  "data": [
    {
      "value": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
      "data": {
        "userUUID": "03eec725-0975-424d-9633-b8b0883ecca7",
        "ip": "91.42.228.239",
        "userAgent": "node",
        "lastActivity": 1757658991409
      }
    }
  ]
}

Delete Token

Delete a specific token.

Endpoint: DELETE /polocloud/api/v3/user/token/{token}

Parameters:

token (path) - The token value to delete

Response:

{
  "status": 204,
  "message": "Token deleted"
}

Error Responses:

404 - Token not found

Delete All Tokens

Delete all your authentication tokens.

Endpoint: DELETE /polocloud/api/v3/user/tokens

Response:

{
  "status": 204,
  "message": "All tokens deleted"
}

User Model

Field	Type	Description
`uuid`	string	Unique user identifier
`username`	string	User's display name
`role`	object	User's role with permissions
`hasChangedPassword`	boolean	Whether user has changed their password
`createdAt`	number	Timestamp when user was created

Usage Examples

Create First Admin User

curl -X POST "http://localhost:8080/polocloud/api/v3/user/self" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your-secure-password",
    "roleId": -1
  }'

Create New User

curl -X POST "http://localhost:8080/polocloud/api/v3/user/" \
  -H "Content-Type: application/json" \
  -H "Cookie: token=YOUR_TOKEN_HERE" \
  -d '{
    "username": "newuser",
    "roleId": 2
  }'

List All Users

curl -X GET "http://localhost:8080/polocloud/api/v3/users/" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Change Password

curl -X PATCH "http://localhost:8080/polocloud/api/v3/user/self/change-password" \
  -H "Content-Type: application/json" \
  -H "Cookie: token=YOUR_TOKEN_HERE" \
  -d '{
    "password": "new-secure-password"
  }'

Delete All Tokens

curl -X DELETE "http://localhost:8080/polocloud/api/v3/user/tokens" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Users

On this page