> ## 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. # List all users > Retrieve a paginated list of all users in the system. **Pagination**: Uses `skip` and `limit` query parameters for pagination. Default limit is 50 users per page, maximum is 100. **Authentication**: Requires a valid JWT token. **Role Aggregation**: Each user in the response includes both direct roles and roles inherited through group memberships. **Use Cases**: - User management dashboards - Administrative user listing - User directory - Bulk user operations - Reporting and analytics **Response Fields**: - `items`: Array of user objects for the current page - `total`: Total number of users in the system - `skip`: Number of users skipped (offset) - `limit`: Maximum number of users returned in this page - `has_more`: Whether there are more users available ## OpenAPI ````yaml https://raw.githubusercontent.com/prefeitura-rio/heimdall/main/docs/api/openapi.json get /api/v1/users/ 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/users/: get: tags: - users summary: List all users description: >- Retrieve a paginated list of all users in the system. **Pagination**: Uses `skip` and `limit` query parameters for pagination. Default limit is 50 users per page, maximum is 100. **Authentication**: Requires a valid JWT token. **Role Aggregation**: Each user in the response includes both direct roles and roles inherited through group memberships. **Use Cases**: - User management dashboards - Administrative user listing - User directory - Bulk user operations - Reporting and analytics **Response Fields**: - `items`: Array of user objects for the current page - `total`: Total number of users in the system - `skip`: Number of users skipped (offset) - `limit`: Maximum number of users returned in this page - `has_more`: Whether there are more users available operationId: list_users_api_v1_users__get parameters: - name: skip in: query required: false schema: type: integer minimum: 0 description: Number of users to skip default: 0 title: Skip description: Number of users to skip - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Maximum number of users to return default: 50 title: Limit description: Maximum number of users to return responses: '200': description: Users retrieved successfully content: application/json: schema: $ref: '#/components/schemas/PaginatedResponse_UserResponse_' example: items: - id: 1 cpf: '12345678901' display_name: João Silva groups: - engineering_team:backend roles: - superadmin - id: 2 cpf: '98765432109' display_name: Maria Santos groups: - data_analysts:read roles: - data-analyst total: 150 skip: 0 limit: 50 has_more: true '401': description: Unauthorized - Invalid or missing JWT token '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal server error security: - HTTPBearer: [] components: schemas: PaginatedResponse_UserResponse_: properties: items: items: $ref: '#/components/schemas/UserResponse' type: array title: Items description: List of items for the current page total: type: integer minimum: 0 title: Total description: Total number of items available example: 150 skip: type: integer minimum: 0 title: Skip description: Number of items skipped (offset) example: 0 limit: type: integer maximum: 100 minimum: 1 title: Limit description: Maximum number of items returned example: 50 has_more: type: boolean title: Has More description: Whether there are more items available example: true type: object required: - items - total - skip - limit - has_more title: PaginatedResponse[UserResponse] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError UserResponse: properties: id: type: integer title: Id description: Unique identifier for the user example: 1 cpf: type: string pattern: ^[0-9]{11}$ title: Cpf description: User's CPF (Cadastro de Pessoa Física) - Brazilian tax ID example: '12345678901' display_name: anyOf: - type: string - type: 'null' title: Display Name description: User's display name from JWT token (name, given_name, or email) example: João Silva groups: items: type: string type: array title: Groups description: List of groups the user belongs to example: - engineering_team:backend - data_analysts:read roles: items: type: string type: array title: Roles description: List of roles assigned to the user (both direct and through groups) example: - superadmin - data-analyst type: object required: - id - cpf title: UserResponse description: Response model for user information. example: cpf: '12345678901' display_name: João Silva groups: - engineering_team:backend - data_analysts:read id: 1 roles: - superadmin - data-analyst 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 ````