Create User

This endpoint allows you to create a new user in your organization. The user can be associated with a user group and will be assigned specific permissions based on their role.

🔹 Endpoint Details

POST /api/v1/users

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Structure

Required Fields

Field	Type	Required	Description	Example
firstName	string	Yes	User's first name	"John"
lastName	string	Yes	User's last name	"Doe"
email	string	Yes	Valid email address	"[email protected]"

Optional Fields

Field	Type	Required	Description	Default
role	enum	No	User's role	"creator"
avatar	string	No	HTTPS URL to avatar	-
userGroupId	string	No	Associated group UUID	-

🧩 Request Example

curl -X POST "https://openapi.onlive.site/api/v1/users/" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "role": "creator",
  "avatar": "https://example.com/avatars/johndoe.jpg",
  "userGroupId": "123e4567-e89b-12d3-a456-426614174000"
}'

📤 Response Format

Successful Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "role": "creator",
  "avatar": "https://example.com/avatars/johndoe.jpg",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "userGroupId": "123e4567-e89b-12d3-a456-426614174001",
  "fullName": "John Doe",
  "createdAt": "2025-05-22T10:30:00Z",
  "updatedAt": "2025-05-22T10:30:00Z"
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input",
  "errors": [
    {
      "field": "email",
      "message": "must be a valid email"
    }
  ]
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid or missing authorization credentials"
}

409 Conflict

{
  "statusCode": 409,
  "message": "User with this email already exists in your organization"
}

📘 Notes

• The organizationId is automatically set from your authentication credentials
• Email addresses must be unique within an organization
• The fullName field is automatically generated from first and last names
• Passwords and authentication are handled through a separate system
• The role defaults to "creator" if not specified
• Avatar URLs must use HTTPS protocol
• Time fields are automatically set and returned in UTC

✅ Common Use Cases

• 👥 New Employee: Create accounts for new team members
• 🔄 System Migration: Bulk import users from another system
• 👥 Team Setup: Create users and assign them to groups
• 🌐 Multi-branch: Create users for different organization locations
• 🤝 Client Access: Create accounts for external collaborators

🔍 Validation Rules

1. Email

   • Must be a valid email format
   • Must be unique within the organization
   • Maximum length: 255 characters

2. Names

   • First and last names required
   • Minimum length: 1 character
   • Maximum length: 100 characters
   • Special characters allowed (for international names)

3. Avatar URL

   • Must be a valid HTTPS URL
   • Maximum length: 2048 characters

4. Role

   • Must be one of: creator, editor, admin
   • Case sensitive
   • Default: creator

---