Users

Manage user accounts, authentication, roles, and soft-delete operations.

All endpoints require Authorization: Bearer <token> and X-SCHOOL-ID headers unless noted otherwise.

---

List Users

GET /users

Returns a paginated list of users for the current school.

Query Parameters

Parameter	Type	Required	Default	Description
pageNumber	integer	Yes	0	Zero-indexed page number
pageSize	integer	Yes	50	Results per page
search	string	No	—	Search by name or username

Example

curl -X GET "https://api.vanillatots.com/users?pageNumber=0&pageSize=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID"

Response 200 OK

{
  "page_number": 0,
  "page_size": 25,
  "total_pages": 4,
  "total": 100,
  "data": [
    {
      "id": "uuid",
      "username": "john.doe",
      "first_name": "John",
      "last_name": "Doe",
      "gender": "Male",
      "photo": "https://...",
      "roles": [
        {
          "roleId": "uuid",
          "userId": "uuid",
          "createdAt": "2024-01-15T10:30:00Z"
        }
      ],
      "school": { "id": "uuid", "name": "...", "..." : "..." },
      "student": null
    }
  ]
}

---

Create User

POST /users

Create a new user account within the current school.

Request Body

Field	Type	Required	Description
username	string	Yes	Unique username (min 1 char)
password	string	Yes	Password (min 1 char)
first_name	string	Yes	First name
last_name	string	Yes	Last name
gender	string	Yes	Gender

Example

curl -X POST https://api.vanillatots.com/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SCHOOL-ID: $SCHOOL_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jane.smith",
    "password": "securePassword123",
    "first_name": "Jane",
    "last_name": "Smith",
    "gender": "Female"
  }'

Response 200 OK — Returns an AuthUser object containing the user profile, access token, and permissions.

{
  "user": { "id": "uuid", "username": "jane.smith", "..." : "..." },
  "access_token": {
    "access_token": "eyJhbG...",
    "expires_in": 86400,
    "token_type": "Bearer"
  },
  "permissions": []
}

---

Login

POST /users/login

Authenticate a user and receive a JWT token.

Request Body

Field	Type	Required	Description
username	string	Yes	Username
password	string	Yes	Password

Example

curl -X POST https://api.vanillatots.com/users/login \
  -H "X-SCHOOL-ID: $SCHOOL_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe",
    "password": "myPassword"
  }'

Response 200 OK — Returns an AuthUser object with access token and permissions.

---

Get User

GET /users/{id}

Retrieve a single user by ID.

Path Parameters

Parameter	Type	Description
id	uuid	User ID

Response 200 OK — Returns a UserResponse object.

---

Delete User

DELETE /users/{id}/delete

Soft-delete a user account.

Path Parameters

Parameter	Type	Description
id	uuid	User ID

Response 200 OK

---

Restore User

PUT /users/{id}/restore

Restore a previously soft-deleted user.

Path Parameters

Parameter	Type	Description
id	uuid	User ID

Response 200 OK — Returns the restored UserResponse.

---

Assign Role

PUT /users/{id}/roles

Assign a role to a user.

Path Parameters

Parameter	Type	Description
id	uuid	User ID

Request Body

Field	Type	Required	Description
role	uuid	Yes	Role ID to assign

Example

curl -X PUT https://api.vanillatots.com/users/{id}/roles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "role": "role-uuid" }'

Response 200 OK — Returns the updated UserResponse.