openapi: 3.0.0
info:
  title: User
  version: 2.0.0
  description: >
    A **User** is an account that can sign in to 4HSE.


    Do not confuse it with **Person**, which is a worker recorded for safety
    compliance: a person

    does not necessarily have an account, and an account does not necessarily
    belong to a worker of

    the company. Compliance data hangs off Person, not off User.


    Access is granted to a user through roles, groups and permissions.


    Use this API to:

    - Register a new account and update its details

    - Search accounts

    - Remove an account
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/user/index:
    post:
      summary: index
      operationId: indexUser
      tags:
        - Users
      description: |
        Returns a paginated and filterable list of users.  
        Use POST to allow complex filters via JSON payload.
      requestBody:
        description: Parameters for searching users
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserIndexParams"
            example:
              filter:
                username: john.doe
                status: active
              per-page: 10
              page: 1
              sort: username
      responses:
        "200":
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ViewUser"
              example:
                user_id: user-1
                username: john.doe
                email: john.doe@example.com
                status: active
                created_at: 1700000000
                updated_at: 1700000001
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/user/view/{id}:
    get:
      summary: view
      operationId: viewUser
      tags:
        - Users
      description: |
        Retrieve a user by its unique ID.
      parameters:
        - name: id
          in: path
          description: ID of the user to retrieve
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewUser"
              example:
                user_id: user-1
                username: john.doe
                email: john.doe@example.com
                status: active
                created_at: 1700000000
                updated_at: 1700000001
        "404":
          description: User not found
  /v2/user/update/{id}:
    put:
      summary: update
      operationId: updateUser
      tags:
        - Users
      description: |
        Update an existing user by its unique ID.
      parameters:
        - name: id
          in: path
          description: ID of the user to update
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: User object with updated data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
            example:
              email: john.doe@newmail.com
              status: inactive
      responses:
        "200":
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              example:
                user_id: user-1
                email: john.doe@newmail.com
                status: inactive
        "404":
          description: User not found
components:
  schemas:
    User:
      type: object
      properties:
        user_id:
          type: string
          format: email
          description: The unique identifier for the user (email address).
        username:
          type: string
          description: The username of the user.
        password_hash:
          type: string
          description: The hashed password for the user.
        password_reset_token:
          type: string
          nullable: true
          description: The token used to reset the user's password (optional).
        email:
          type: string
          description: The email address of the user.
        auth_key:
          type: string
          description: The authentication key used for the user's sessions.
        status:
          type: string
          description: The current status of the user (e.g., active, inactive, etc.).
        created_at:
          type: integer
          description: The timestamp when the user was created.
        updated_at:
          type: integer
          description: The timestamp when the user was last updated.
        password:
          type: string
          writeOnly: true
          description: The user's password, which is write-only and not retrievable.
    ViewUser:
      type: object
      properties:
        user_id:
          type: string
          format: email
          description: The unique identifier for the user (email address).
        username:
          type: string
          description: The username of the user.
        email:
          type: string
          description: The email address of the user.
        status:
          type: string
          description: The current status of the user (e.g., active, inactive, etc.).
        created_at:
          type: integer
          description: The timestamp when the user was created.
        updated_at:
          type: integer
          description: The timestamp when the user was last updated.
    UserIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/ViewUser"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          description: Field to sort by. Prefix with minus for descending order (e.g.
            -username).
          enum:
            - username
            - email
            - status
      example:
        filter:
          status: active
        per-page: 100
        page: 1
        sort: username
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
