Skip to main content
The Users API allows administrators to create, list, and delete user accounts. All user management operations require admin privileges.
All endpoints on this page require admin authentication. Regular users cannot access user management functions.

​
Create a user

Create a new user account. Only admins can create users. 
curl -X POST http://localhost:4000/users \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "[email protected]",
    "password": "secure_password_here"
  }'

​
Request

​
username
string
required
Unique username for the new user. Must not already exist in the system.
​
email
string
required
Email address for the user
​
password
string
required
Password for the user. Will be securely hashed using bcrypt before storage.

​
Response

​
id
string
Unique identifier (UUID) for the user
​
username
string
Username of the created user
​
email
string
Email address of the user
​
is_admin
boolean
Whether the user has admin privileges (always false for newly created users)

​
Error responses

409 Conflict - Username already exists: 
user with username 'newuser' already exists
403 Forbidden - Non-admin user attempted to create a user: 
Only admins can create new users
401 Unauthorized - No authentication provided: 
Unauthorized

​
List all users

Retrieve a list of all users in the system. 
curl http://localhost:4000/users \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

Returns an array of user objects. Passwords are never included in responses.
This endpoint is available to all authenticated users, not just admins. It’s useful for discovering usernames when sharing filters.

​
Delete a user

Permanently remove a user account. Only admins can delete users. 
curl -X DELETE http://localhost:4000/users/USER_ID \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

​
Path parameters

​
user_id
string
required
The unique identifier (UUID) of the user to delete

​
Response

200 OK - User deleted successfully: 
{
  "status": "success",
  "message": "user ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' deleted successfully"
}
404 Not Found - User doesn’t exist: 
user not found
403 Forbidden - Non-admin attempted deletion: 
Only admins can delete users
User deletion is permanent and cannot be undone. Ensure you have the correct user ID before deleting.

​
User security

​
Password storage

Passwords are securely hashed using bcrypt with the default cost factor (10 rounds) before being stored in the database. Passwords are never returned in API responses.

​
Admin privileges

New users are always created with is_admin: false. Admin status cannot be set through the API and must be configured directly in the database or through the configuration file for the default admin account.

​
Default admin account

BOOM creates a default admin account on startup with credentials configured in config.yaml: 
api:
  auth:
    admin_username: admin  # Set via BOOM_API__AUTH__ADMIN_USERNAME
    admin_password: ""     # Set via BOOM_API__AUTH__ADMIN_PASSWORD (required)
    admin_email: [email protected]
Always set a strong password for the admin account via the BOOM_API__AUTH__ADMIN_PASSWORD environment variable. Never use the default value in production.

​
User permissions

Users have the following permissions:
ActionRegular UserAdmin
Create filters✓✓
View own filters✓✓
View all filters✗✓
Modify own filters✓✓
Modify any filter✗✓
List users✓✓
Create users✗✓
Delete users✗✓
Run queries✓✓

​
Best practices

  1. Limit admin accounts - Only create admin accounts for users who need full system access
  2. Strong passwords - Enforce strong password policies for all users
  3. Regular audits - Periodically review the user list and remove inactive accounts
  4. Unique usernames - Use descriptive, unique usernames for easier identification
  5. Email verification - Consider implementing email verification in your workflow (not built into the API)

Build docs developers (and LLMs) love

Get started for freeTalk to us