Create new user (admin only)
Creates a new user account with specified role and permissions.
## Authorization
- **Required Role**: Admin only
- Non-admins receive 403 Forbidden
## Behavior
- Validates email uniqueness in Better Auth users collection
- Hashes password with bcrypt (12 rounds)
- Generates secure user ID
- Sets default values for optional fields
- Creates user record in better_auth_users collection
- Returns created user data (excluding password hash)
## Password Rules
- Minimum 8 characters
- Must include: uppercase, lowercase, digit, special character
- Or omit password to require password reset on first login
## Default Values
- is_active: true
- is_verified: false (requires email confirmation)
- timezone: America/Los_Angeles
- login_count: 0
## Performance
- **Timeout**: 10 seconds
- **Database calls**: 2 queries (duplicate check, user create)
## Examples
```json
POST /api/v1/users
{
"email": "newagent@brokerage.com",
"password": "SecurePass123!",
"name": "John Doe",
"role": "agent",
"first_name": "John",
"last_name": "Doe",
"brokerage_name": "Elite Realty",
"office_name": "Downtown Office"
}
```
| Method | Path |
|---|---|
POST | /api/v1/users/ |
Primary host: https://valara.cloud (legacy alias: https://dash.jacoballenmedia.com).
Parameters
(no path or query parameters)
Request body
(no request body)
Response
null
Responses
| Status | Description |
|---|---|
201 | User created successfully |
400 | Validation error - email already exists or invalid data (see error codes) |
401 | Authentication required (see error codes) |
403 | Forbidden - admin role required (see error codes) |
422 | Validation Error (see error codes) |
500 | Server error - user creation failed (see error codes) |
Examples
curl
curl -X POST "https://valara.cloud/api/v1/users/" \
-H "Authorization: Bearer $VALARA_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: $(uuidgen)"
Python
import os
import uuid
import httpx
res = httpx.request(
"POST",
"https://valara.cloud/api/v1/users/",
headers={
"Authorization": f"Bearer {os.environ['VALARA_API_KEY']}",
"Content-Type": "application/json",
"X-Idempotency-Key": str(uuid.uuid4()),
},
)
res.raise_for_status()
print(res.json())