auth-framework 0.5.0-rc19

# Administrative Endpoints

users:
    get:
        tags:
            - Admin
        summary: List users
        operationId: listUsers
        security:
            - bearerAuth: []
        parameters:
            - $ref: "../components/parameters.yaml#/PageParam"
            - $ref: "../components/parameters.yaml#/LimitParam"
            - name: search
              in: query
              schema:
                  type: string
            - name: role
              in: query
              schema:
                  type: string
            - name: active
              in: query
              schema:
                  type: boolean
        responses:
            "200":
                description: Users retrieved successfully
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "../schemas/common.yaml#/ApiResponse"
                                - type: object
                                  properties:
                                      data:
                                          $ref: "../schemas/users.yaml#/UserListResponse"
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"

    post:
        tags:
            - Admin
        summary: Create a user
        operationId: createUser
        security:
            - bearerAuth: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        $ref: "../schemas/users.yaml#/CreateUserRequest"
        responses:
            "200":
                description: User created successfully
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "../schemas/common.yaml#/ApiResponse"
                                - type: object
                                  properties:
                                      data:
                                          $ref: "../schemas/users.yaml#/UserListItem"
            "400":
                $ref: "../components/responses.yaml#/BadRequest"
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"

userById:
    delete:
        tags:
            - Admin
        summary: Delete a user
        operationId: deleteUser
        security:
            - bearerAuth: []
        parameters:
            - name: user_id
              in: path
              required: true
              schema:
                  type: string
              example: "user_123"
        responses:
            "200":
                description: User deleted successfully
                content:
                    application/json:
                        schema:
                            $ref: "../schemas/common.yaml#/ApiResponse"
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"
            "404":
                $ref: "../components/responses.yaml#/NotFound"

userRoles:
    put:
        tags:
            - Admin
        summary: Replace a user's roles
        operationId: updateUserRoles
        security:
            - bearerAuth: []
        parameters:
            - name: user_id
              in: path
              required: true
              schema:
                  type: string
              example: "user_123"
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        $ref: "../schemas/users.yaml#/UpdateUserRolesRequest"
        responses:
            "200":
                description: User roles updated successfully
                content:
                    application/json:
                        schema:
                            $ref: "../schemas/common.yaml#/ApiResponse"
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"

activateUser:
    put:
        tags:
            - Admin
        summary: Activate or deactivate a user
        operationId: activateUser
        security:
            - bearerAuth: []
        parameters:
            - name: user_id
              in: path
              required: true
              schema:
                  type: string
              example: "user_123"
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        $ref: "../schemas/users.yaml#/ActivateUserRequest"
        responses:
            "200":
                description: User activation state updated successfully
                content:
                    application/json:
                        schema:
                            $ref: "../schemas/common.yaml#/ApiResponse"
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"

stats:
    get:
        tags:
            - Admin
        summary: Get system statistics
        operationId: getSystemStats
        security:
            - bearerAuth: []
        responses:
            "200":
                description: System statistics returned successfully
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "../schemas/common.yaml#/ApiResponse"
                                - type: object
                                  properties:
                                      data:
                                          type: object
                                          properties:
                                              total_users:
                                                  type: integer
                                              active_sessions:
                                                  type: integer
                                              total_tokens:
                                                  type: integer
                                              failed_logins_24h:
                                                  type: integer
                                              system_uptime:
                                                  type: string
                                              memory_usage:
                                                  type: string
                                              cpu_usage:
                                                  type: string
                                          required:
                                              - total_users
                                              - active_sessions
                                              - total_tokens
                                              - failed_logins_24h
                                              - system_uptime
                                              - memory_usage
                                              - cpu_usage
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"

auditLogs:
    get:
        tags:
            - Admin
        summary: Query audit logs
        operationId: getAuditLogs
        security:
            - bearerAuth: []
        parameters:
            - $ref: "../components/parameters.yaml#/PageParam"
            - $ref: "../components/parameters.yaml#/LimitParam"
            - name: user_id
              in: query
              schema:
                  type: string
            - name: action
              in: query
              schema:
                  type: string
            - name: start_date
              in: query
              schema:
                  type: string
            - name: end_date
              in: query
              schema:
                  type: string
            - name: risk_level
              in: query
              schema:
                  type: string
            - name: outcome
              in: query
              schema:
                  type: string
            - name: correlation_id
              in: query
              schema:
                  type: string
            - name: ip_address
              in: query
              schema:
                  type: string
        responses:
            "200":
                description: Audit logs returned successfully
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "../schemas/common.yaml#/ApiResponse"
                                - type: object
                                  properties:
                                      data:
                                          type: object
                                          properties:
                                              logs:
                                                  type: array
                                                  items:
                                                      type: object
                                                      properties:
                                                          id:
                                                              type: string
                                                          timestamp:
                                                              type: string
                                                          user_id:
                                                              type: string
                                                          action:
                                                              type: string
                                                          resource:
                                                              type: string
                                                          ip_address:
                                                              type: string
                                                          user_agent:
                                                              type: string
                                                          result:
                                                              type: string
                                                          risk_level:
                                                              type: string
                                                          outcome:
                                                              type: string
                                                          correlation_id:
                                                              type: string
                                                              nullable: true
                                              pagination:
                                                  $ref: "../schemas/common.yaml#/Pagination"
                                          required:
                                              - logs
                                              - pagination
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"

auditLogStats:
    get:
        tags:
            - Admin
        summary: Get audit-log summary statistics
        operationId: getAuditLogStats
        security:
            - bearerAuth: []
        responses:
            "200":
                description: Audit-log statistics returned successfully
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "../schemas/common.yaml#/ApiResponse"
                                - type: object
                                  properties:
                                      data:
                                          type: object
                                          properties:
                                              total_events_24h:
                                                  type: integer
                                              failed_logins_24h:
                                                  type: integer
                                              successful_logins_24h:
                                                  type: integer
                                              high_risk_events_24h:
                                                  type: integer
                                              unique_users_24h:
                                                  type: integer
                                              security_alerts_24h:
                                                  type: integer
                                          required:
                                              - total_events_24h
                                              - failed_logins_24h
                                              - successful_logins_24h
                                              - high_risk_events_24h
                                              - unique_users_24h
                                              - security_alerts_24h
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"

config:
    get:
        tags:
            - Admin
        summary: Read runtime-mutable configuration
        operationId: getAdminConfig
        security:
            - bearerAuth: []
        responses:
            "200":
                description: Runtime configuration returned successfully
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "../schemas/common.yaml#/ApiResponse"
                                - type: object
                                  properties:
                                      data:
                                          type: object
                                          properties:
                                              token_lifetime_secs:
                                                  type: integer
                                              refresh_token_lifetime_secs:
                                                  type: integer
                                              enable_multi_factor:
                                                  type: boolean
                                              rate_limiting_enabled:
                                                  type: boolean
                                              rate_limit_max_requests:
                                                  type: integer
                                              rate_limit_window_secs:
                                                  type: integer
                                              rate_limit_burst:
                                                  type: integer
                                              min_password_length:
                                                  type: integer
                                              require_password_complexity:
                                                  type: boolean
                                              secure_cookies:
                                                  type: boolean
                                              csrf_protection:
                                                  type: boolean
                                              session_timeout_secs:
                                                  type: integer
                                              audit_enabled:
                                                  type: boolean
                                              audit_log_success:
                                                  type: boolean
                                              audit_log_failures:
                                                  type: boolean
                                              audit_log_permissions:
                                                  type: boolean
                                              audit_log_tokens:
                                                  type: boolean
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"

    put:
        tags:
            - Admin
        summary: Partially update runtime-mutable configuration
        operationId: updateAdminConfig
        security:
            - bearerAuth: []
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        additionalProperties: false
                        properties:
                            token_lifetime_secs:
                                type: integer
                            refresh_token_lifetime_secs:
                                type: integer
                            enable_multi_factor:
                                type: boolean
                            rate_limiting_enabled:
                                type: boolean
                            rate_limit_max_requests:
                                type: integer
                            rate_limit_window_secs:
                                type: integer
                            rate_limit_burst:
                                type: integer
                            min_password_length:
                                type: integer
                            require_password_complexity:
                                type: boolean
                            secure_cookies:
                                type: boolean
                            csrf_protection:
                                type: boolean
                            session_timeout_secs:
                                type: integer
                            audit_enabled:
                                type: boolean
                            audit_log_success:
                                type: boolean
                            audit_log_failures:
                                type: boolean
                            audit_log_permissions:
                                type: boolean
                            audit_log_tokens:
                                type: boolean
        responses:
            "200":
                description: Runtime configuration updated successfully
                content:
                    application/json:
                        schema:
                            allOf:
                                - $ref: "../schemas/common.yaml#/ApiResponse"
                                - type: object
                                  properties:
                                      data:
                                          type: object
            "400":
                $ref: "../components/responses.yaml#/BadRequest"
            "401":
                $ref: "../components/responses.yaml#/Unauthorized"
            "403":
                $ref: "../components/responses.yaml#/Forbidden"