> ## 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 action > Create a new action that can be used in authorization policies and endpoint mappings. **Actions**: Define granular permissions available in the system. Examples include `user:read`, `group:create`, `data:export`, etc. **Authorization**: Requires admin privileges to create actions. **Naming Convention**: Use colon-separated format like `resource:operation` (e.g., `user:read`, `group:create`, `data:export`). **Use Cases**: - Define new permissions for application features - Create fine-grained access controls - Integrate with external authorization systems - Map API endpoints to specific actions **Endpoint Mapping**: Actions can be mapped to API endpoints using the mappings API. ## OpenAPI ````yaml https://raw.githubusercontent.com/prefeitura-rio/heimdall/main/docs/api/openapi.json post /api/v1/actions/ 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/actions/: post: tags: - actions summary: Create a new action description: >- Create a new action that can be used in authorization policies and endpoint mappings. **Actions**: Define granular permissions available in the system. Examples include `user:read`, `group:create`, `data:export`, etc. **Authorization**: Requires admin privileges to create actions. **Naming Convention**: Use colon-separated format like `resource:operation` (e.g., `user:read`, `group:create`, `data:export`). **Use Cases**: - Define new permissions for application features - Create fine-grained access controls - Integrate with external authorization systems - Map API endpoints to specific actions **Endpoint Mapping**: Actions can be mapped to API endpoints using the mappings API. operationId: create_action_api_v1_actions__post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ActionCreateRequest' responses: '201': description: Action created successfully content: application/json: schema: $ref: '#/components/schemas/app__routers__actions__ActionResponse' example: id: 1 name: user:read description: Read user information endpoint_count: 0 '400': description: Bad request - Invalid input data or duplicate action name content: application/json: example: detail: Action with name 'user:read' already exists '401': description: Unauthorized - Invalid or missing JWT token content: application/json: example: detail: Could not validate credentials '403': description: Forbidden - Insufficient permissions to create actions content: application/json: example: detail: Insufficient permissions to create actions '422': description: Validation error - Invalid action data format content: application/json: example: detail: Validation error errors: - loc: - body - name msg: string does not match regex type: value_error.regex '500': description: Internal server error content: application/json: example: detail: 'Failed to create action: Database connection error' security: - HTTPBearer: [] components: schemas: ActionCreateRequest: properties: name: type: string maxLength: 100 minLength: 1 pattern: ^[a-z0-9_:]+$ title: Name description: >- Unique name for the action (lowercase letters, numbers, underscores, and colons only) example: user:read description: type: string maxLength: 500 minLength: 1 title: Description description: Human-readable description of the action's purpose example: Read user information type: object required: - name - description title: ActionCreateRequest description: Request model for creating a new action. example: description: Read user information name: user:read app__routers__actions__ActionResponse: properties: id: type: integer title: Id description: Unique identifier for the action example: 1 name: type: string title: Name description: Action name example: user:read description: anyOf: - type: string - type: 'null' title: Description description: Action description example: Read user information endpoint_count: type: integer title: Endpoint Count description: Number of API endpoints mapped to this action default: 0 example: 3 type: object required: - id - name title: ActionResponse description: Response model for action information. example: description: Read user information endpoint_count: 3 id: 1 name: user:read securitySchemes: HTTPBearer: type: http scheme: bearer ````