> ## Documentation Index > Fetch the complete documentation index at: https://docs.dados.rio/llms.txt > Use this file to discover all available pages before exploring further. # Create a new group > Create a new group in the system. **Authorization Required**: Users must have permission to create groups via Cerbos policies. **Notes**: - Group names must be unique across the system - Names can only contain alphanumeric characters, hyphens, and underscores - The creating user becomes the group owner - Group creation is audited and logged **Common Use Cases**: - Creating departmental groups (e.g., "engineering", "marketing") - Setting up project teams with specific access requirements - Organizing users by geographical location or business unit ## OpenAPI ````yaml https://raw.githubusercontent.com/prefeitura-rio/heimdall/main/docs/api/openapi.json post /api/v1/groups/ openapi: 3.1.0 info: title: Heimdall Admin Service description: >- # Heimdall Admin Service API A comprehensive admin service for user and group management with authorization powered by Cerbos. ## Features - **User Management**: Automatic user creation from JWT tokens with role-based access control - **Group Management**: Create, manage, and assign users to groups with hierarchical permissions - **Role Management**: Define and assign roles to users and groups - **Mapping Management**: Configure API endpoint to action mappings for authorization - **Action Management**: Define available actions for fine-grained permission control - **Cerbos Integration**: Policy-based authorization with external Cerbos service - **Audit Logging**: Comprehensive audit trail for all administrative operations - **Redis Caching**: High-performance caching for frequently accessed data version: 1.0.0 servers: - url: https://services.pref.rio/heimdall-admin description: Production server - url: https://services.staging.app.dados.rio/heimdall-admin description: Staging server security: [] tags: - name: health description: Service health and readiness checks - name: users description: >- User management operations. Users are automatically created from JWT tokens. - name: groups description: >- Group management operations. Groups organize users and can have roles assigned. - name: memberships description: Group membership management. Assign and remove users from groups. - name: roles description: >- Role management operations. Roles define permissions that can be assigned to users or groups. - name: actions description: >- Action management operations. Actions define the granular permissions available in the system. - name: mappings description: >- API endpoint to action mapping configuration. Maps HTTP endpoints to authorization actions. paths: /api/v1/groups/: post: tags: - groups summary: Create a new group description: >- Create a new group in the system. **Authorization Required**: Users must have permission to create groups via Cerbos policies. **Notes**: - Group names must be unique across the system - Names can only contain alphanumeric characters, hyphens, and underscores - The creating user becomes the group owner - Group creation is audited and logged **Common Use Cases**: - Creating departmental groups (e.g., "engineering", "marketing") - Setting up project teams with specific access requirements - Organizing users by geographical location or business unit operationId: create_group_api_v1_groups__post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GroupCreateRequest' responses: '201': description: Group created successfully content: application/json: schema: $ref: '#/components/schemas/GroupResponse' example: id: 1 name: engineering_team:backend description: Engineering team with access to development resources created_by: '12345678901' created_at: '2024-01-15T10:30:00Z' '400': description: Bad request - Invalid input data content: application/json: example: detail: Group name contains invalid characters '401': description: Unauthorized - Invalid or missing JWT token content: application/json: example: detail: Could not validate credentials '403': description: Forbidden - Insufficient permissions to create groups content: application/json: example: detail: Permission denied to create group 'engineering_team:backend' '409': description: Conflict - Group with this name already exists content: application/json: example: detail: Group with name 'engineering_team:backend' already exists '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal server error content: application/json: example: detail: An unexpected error occurred while creating the group security: - HTTPBearer: [] components: schemas: GroupCreateRequest: properties: name: type: string maxLength: 100 minLength: 1 pattern: ^[a-z0-9_:]+$ title: Name description: >- Unique name for the group (lowercase letters, numbers, underscores, and colons only) example: engineering_team:backend description: type: string maxLength: 500 minLength: 1 title: Description description: Human-readable description of the group's purpose example: Engineering team with access to development resources type: object required: - name - description title: GroupCreateRequest description: Request model for creating a new group. example: description: Engineering team with access to development resources name: engineering_team:backend GroupResponse: properties: id: type: integer title: Id description: Unique identifier for the group example: 1 name: type: string title: Name description: Group name example: engineering_team:backend description: type: string title: Description description: Group description example: Engineering team with access to development resources created_by: anyOf: - type: string - type: 'null' title: Created By description: CPF of the user who created this group example: '12345678901' created_at: type: string title: Created At description: ISO timestamp when the group was created example: '2024-01-15T10:30:00Z' type: object required: - id - name - description - created_at title: GroupResponse description: Response model for group information. example: created_at: '2024-01-15T10:30:00Z' created_by: '12345678901' description: Engineering team with access to development resources id: 1 name: engineering_team:backend HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ````