Create User Group

This endpoint allows you to create a new user group within an organization. User groups help organize users and manage permissions effectively.

🔹 Endpoint Details

POST /api/v1/user-groups

🔒 Authentication

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

📝 Request Structure

Request Body Properties

Field	Type	Required	Description	Example
name	string	Yes	Name of the user group (min length: 1)	"Sales Team"
description	string	No	Detailed description of the group's purpose	"Sales team with product access"
externalId	string	No	External identifier for system integration	"SALES_TEAM_01"
extraFields	object	No	Additional custom fields	See example below

🧩 Request Example

curl -X POST "https://openapi.onlive.site/api/v1/user-groups/" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "name": "Sales Team",
  "description": "Sales team members with access to product management",
  "externalId": "SALES_TEAM_01",
  "extraFields": {
    "department": "Sales",
    "location": "New York",
    "allowedFeatures": [
      "product_management",
      "sales_reports"
    ]
  }
}'

📤 Response Format

Successful Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Sales Team",
  "description": "Sales team members with access to product management",
  "externalId": "SALES_TEAM_01",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "extraFields": {
    "department": "Sales",
    "location": "New York",
    "allowedFeatures": ["product_management", "sales_reports"]
  },
  "createdAt": "2025-05-22T10:30:00Z",
  "updatedAt": "2025-05-22T10:30:00Z"
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input",
  "errors": [
    {
      "field": "name",
      "message": "name must not be empty"
    }
  ]
}

401 Unauthorized

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

409 Conflict

{
  "statusCode": 409,
  "message": "A user group with this externalId already exists"
}

📘 Notes

• The organizationId is automatically derived from your authentication credentials
• The response includes system-generated fields:
  • id: Unique identifier for the group
  • organizationId: Your organization's ID
  • createdAt: Creation timestamp
  • updatedAt: Last modification timestamp
• All timestamps are in ISO 8601 format with UTC timezone
• The extraFields object can contain any valid JSON structure

✅ Common Use Cases

• 👥 New Department: Create a group for a new department or team
• 🔐 Access Control: Set up groups with specific feature permissions
• 🌍 Regional Teams: Create groups for different office locations
• 📊 Project Teams: Organize users by project or function
• 🔄 System Integration: Create groups that map to external systems

---