> ## 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 endpoint-to-action mapping > Create a new mapping between an API endpoint pattern and an action. **Authorization**: Requires admin privileges to create mappings. **Path Patterns**: Support exact paths and parameterized paths using curly braces (e.g., `/api/v1/users/{user_id}`, `/api/v1/groups/{group_name}/members`). **Method Mapping**: Each combination of path pattern and HTTP method can only be mapped to one action. **Action Reference**: The action must exist before creating a mapping. Use the actions API to create actions first. **Use Cases**: - Configure authorization for new API endpoints - Map existing endpoints to granular permissions - Set up fine-grained access control - Administrative configuration of API security ## OpenAPI ````yaml https://raw.githubusercontent.com/prefeitura-rio/heimdall/main/docs/api/openapi.json post /api/v1/mappings/ 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/mappings/: post: tags: - mappings summary: Create endpoint-to-action mapping description: >- Create a new mapping between an API endpoint pattern and an action. **Authorization**: Requires admin privileges to create mappings. **Path Patterns**: Support exact paths and parameterized paths using curly braces (e.g., `/api/v1/users/{user_id}`, `/api/v1/groups/{group_name}/members`). **Method Mapping**: Each combination of path pattern and HTTP method can only be mapped to one action. **Action Reference**: The action must exist before creating a mapping. Use the actions API to create actions first. **Use Cases**: - Configure authorization for new API endpoints - Map existing endpoints to granular permissions - Set up fine-grained access control - Administrative configuration of API security operationId: create_mapping_api_v1_mappings__post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MappingCreateRequest' responses: '201': description: Mapping created successfully content: application/json: schema: $ref: '#/components/schemas/MappingDetailResponse' example: id: 1 path_pattern: /api/v1/users/{user_id} method: GET action: user:read description: Get user profile information created_by: '12345678901' created_at: '2024-01-15T10:30:00Z' '400': description: Bad request - Invalid action ID content: application/json: example: detail: Action with ID 999 does not exist '401': description: Unauthorized - Invalid or missing JWT token content: application/json: example: detail: Could not validate credentials '403': description: Forbidden - Insufficient permissions to create mappings content: application/json: example: detail: Permission denied to create mappings '409': description: Conflict - Mapping already exists for this path and method content: application/json: example: detail: >- Mapping already exists for path '/api/v1/users/{user_id}' and method 'GET' '422': description: Validation error - Invalid request data content: application/json: example: detail: Validation error errors: - loc: - body - method msg: string does not match regex type: value_error.regex '500': description: Internal server error content: application/json: example: detail: 'Failed to create mapping: Database connection error' security: - HTTPBearer: [] components: schemas: MappingCreateRequest: properties: path_pattern: type: string maxLength: 255 minLength: 1 title: Path Pattern description: URL path pattern (supports wildcards and path parameters) example: /api/v1/users/{user_id} method: type: string pattern: ^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$ title: Method description: HTTP method example: GET action_id: type: integer exclusiveMinimum: 0 title: Action Id description: ID of the action to map to this endpoint example: 1 description: anyOf: - type: string maxLength: 500 - type: 'null' title: Description description: Optional description of this mapping example: Get user profile information type: object required: - path_pattern - method - action_id title: MappingCreateRequest description: Request model for creating a new endpoint-to-action mapping. example: action_id: 1 description: Get user profile information method: GET path_pattern: /api/v1/users/{user_id} MappingDetailResponse: properties: id: type: integer title: Id description: Unique identifier of the mapping example: 1 path_pattern: type: string title: Path Pattern description: URL path pattern example: /api/v1/users/{user_id} method: type: string title: Method description: HTTP method example: GET action: type: string title: Action description: Action name example: user:read description: anyOf: - type: string - type: 'null' title: Description description: Mapping description example: Get user profile information created_by: anyOf: - type: string - type: 'null' title: Created By description: CPF of the user who created this mapping example: '12345678901' created_at: type: string title: Created At description: ISO timestamp when the mapping was created example: '2024-01-15T10:30:00Z' updated_at: anyOf: - type: string - type: 'null' title: Updated At description: ISO timestamp when the mapping was last updated example: '2024-01-16T14:20:00Z' type: object required: - id - path_pattern - method - action - created_at title: MappingDetailResponse description: Detailed response model for mapping information. example: action: user:read created_at: '2024-01-15T10:30:00Z' created_by: '12345678901' description: Get user profile information id: 1 method: GET path_pattern: /api/v1/users/{user_id} updated_at: '2024-01-16T14:20:00Z' securitySchemes: HTTPBearer: type: http scheme: bearer ````