Users

User management endpoints.

Base path: /api/v1/users

All endpoints except GET /me and PATCH /me/password require the appropriate permission.

List Users

GET /api/v1/users

Required permission: users:read

Query parameters

Parameter	Type	Default	Description
`page`	int	`1`	Page number
`per_page`	int	`20`	Items per page
`first_name`	string	—	Search by first name or last name (case-insensitive)
`last_name`	string	—	Search by last name (case-insensitive)
`email`	string	—	Filter by email (partial match)
`is_active`	boolean	—	Filter by active status

Response 200 OK

{
  "data": [
    {
      "id": "uuid",
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "is_active": true
    }
  ],
  "pagination": {
    "total": 201,
    "page": 1,
    "per_page": 20,
    "pages": 11,
    "has_next": true,
    "has_prev": false
  }
}

Create User

POST /api/v1/users

Required permission: users:create

Request body

{
  "email": "user@example.com",
  "password": "Password123!",
  "first_name": "John",
  "last_name": "Doe"
}

Response 201 Created — full UserResponse object.

Errors

Status	Description
`409`	Email already registered
`422`	Validation error

Get Current User

Returns the authenticated user's own profile. Does not require any permission beyond being logged in.

GET /api/v1/users/me

Response 200 OK — full UserResponse object.

Get User

GET /api/v1/users/{id}

Required permission: users:read

Response 200 OK — full UserResponse object.

Errors

Status	Description
`404`	User not found

Update User

PATCH /api/v1/users/{id}

Required permission: users:update

Request body — all fields optional

{
  "first_name": "Jane",
  "last_name": "Doe",
  "is_active": false
}

Response 200 OK — updated UserResponse object.

Update Own Password

Allows the authenticated user to change their own password without requiring any special permission.

PATCH /api/v1/users/me/password

Request body

{
  "current_password": "OldPassword123!",
  "new_password": "NewPassword123!"
}

Response 204 No Content

Errors

Status	Description
`400`	Current password is incorrect
`400`	New password must differ from current

Assign Roles

Replaces all roles assigned to a user with the provided list.

POST /api/v1/users/{id}/roles

Required permission: users:assign_roles

Request body

{
  "role_ids": [
    "uuid-of-role-1",
    "uuid-of-role-2"
  ]
}

Response 200 OK — updated UserResponse object.

Errors

Status	Description
`400`	One or more roles not found
`404`	User not found

Warning

This endpoint replaces all existing role assignments. To keep existing roles, include their IDs in the request.

Delete User

Soft-deletes a user. The record remains in the database with deleted_at set.

DELETE /api/v1/users/{id}

Required permission: users:delete

Response 204 No Content

Errors

Status	Description
`404`	User not found