openapi: 3.0.0
info:
  title: IED Auth APIs
  version: '0.1'
  description: IED Auth API documentation.
  contact:
    name: Team WoA
  license:
    name: Industrial Edge © 2025, Siemens AG. All rights reserved.
servers:
  - url: https://localhost/device/edge/a.service/api/v3
    description: Localhost
tags:
  - name: settings
    description: Edge auth service Settings endpoint.
  - name: users
    description: Edge auth service Users endpoint (Users refer to all authorized users of the edge device, regardless of the application(s) they might use.)
paths:
  '/settings/login-attempts':
    get:
      tags:
        - settings
      summary: Provide login attempts settings values.
      responses:
        '204':
          $ref: '#/components/responses/loginAttemptsSettings'
        '401':
          $ref: '#/components/responses/errorUnauthenticated'
        "403":
          $ref: "#/components/responses/errorForbidden"
        '500':
          $ref: '#/components/responses/genericError'
      operationId: get-login-attempts-settings
      description: |-
        Get Login Attempts Settings is a function to retreive the current values for the login attempt functionality.
      parameters:
        - $ref: '#/components/parameters/Authorization'
      security:
        - API-Key: []
    put:
      tags:
        - settings
      summary: Update login attempts settings values.
      operationId: put-login-attempts-settings
      description: |-
        Update Login Attempts Settings is a function to update the current values for the login attempt functionality.
      requestBody:
        $ref: "#/components/requestBodies/LoginAttemptsSettings"
      responses:
        '204':
          description: Login attempts settings updated successfully.
        '400':
          $ref: '#/components/responses/loginAttemptsSettingsInvalidInput'
        '401':
          $ref: '#/components/responses/errorUnauthenticated'
        "403":
          $ref: "#/components/responses/errorForbidden"
        '500':
          $ref: '#/components/responses/genericError'
      parameters:
        - $ref: '#/components/parameters/Authorization'
      security:
        - API-Key: []
  '/users/{userId}/unblock':
    parameters:
      - schema:
          type: string
          format: uuid
        name: userId
        in: path
        required: true
        description: Maps to a user
    put:
      tags:
        - users
      summary: Unblock a user.
      operationId: unblock-user
      description: |-
        Unblock User is a function to unblock a user who has been blocked due to exceeding the allowed number of login attempts, by an Admin.
      responses:
        '204':
          description: Unblock user successfully.
        '400':
          $ref: '#/components/responses/userUnblockInvalidInput'
        '401':
          $ref: '#/components/responses/errorUnauthenticated'
        "403":
          $ref: "#/components/responses/errorForbidden"
        "404":
          $ref: '#/components/responses/errorUserNotFound'
        '500':
          $ref: '#/components/responses/genericError'
      parameters:
        - $ref: '#/components/parameters/Authorization'
      security:
        - API-Key: []

components:
  schemas:
    errors.generic:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: "0x00000001"
              status:
                type: integer
                example: 500
              title:
                type: string
                example: "Internal Server Error"
              correlationId:
                type: string
              source:
                type: object
                description: Optional or will have one of the following members
                properties:
                  parameter:
                    type: string
                    description: a string that indicates which URI query parameter caused the error.
                  pointer:
                    type: string
                    description: JSON pointer to the value in the request document that caused the error. Example, "/data" for a primary data object, or "/data/attributes/title" for a specific attribute.
                  header:
                    type: string
                    description: a string that indicates the name of a the header property which caused the error.
                  resourceId:
                    type: string
                    description: a string that indicates the id of the resource which caused the error.
    Error:
      description: Error consist of code which is associated with a title, status and correlationId which is a uuid, used to distincly identify the error.
      type: object
      x-examples:
        ExampleError:
          code: auth.application.notFound
          logref: c105072b-39cb-49d9-999f-3873b10e3db1
          message: Application not found.
      properties:
        code:
          type: string
          minLength: 1
        status:
          type: integer
          minimum: 400
          maximum: 599
          description: HTTP status code associated with the error.
        title:
          type: string
          minLength: 1
        correlationId:
          type: string
          minLength: 1
          format: uuid
          description: Unique uuid generated for each error
      required:
        - code
        - status
        - title
    ErrorResponse:
      description: |-
        - The Error response is list of errors.
        - The errors if present more than one is sent in succession. 
        - Array of errors returns all error at once, rather than sending them sepearately.
      type: object
      x-examples:
        ExampleErrorList:
          errors:
            - code: auth.application.notFound
              logref: c105072b-39cb-49d9-999f-3873b10e3db1
              message: Application not found.
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    LoginAttemptsSettings:
      type: object
      properties:
        NoOfAttempts:
          type: integer
          description: Number of login attempts allowed before blocking the user.
          example: 5
          minimum: 1
          maximum: 255
        LoginResetTime:
          type: string
          description: Time duration with no unsuccessful login attempt after which the login attempts are reset.
          example: "15m"
          minLength: 1
          format: duration string format # Duration string format, e.g., "15m" for 15 minutes, "1h" for 1 hour
        LoginBlockingTime:
          type: string
          description: Time duration for which the user is blocked after exceeding login attempts.
          example: "15m"
          minLength: 1
          format: duration string format # Duration string format, e.g., "15m" for 15 minutes, "1h" for 1 hour
        LoginAttemptFunctionalityEnabled:
          type: boolean
          description: Indicates if the login attempt functionality is enabled or not.
          example: true

  requestBodies:
    LoginAttemptsSettings:
      description: Login attempts settings
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LoginAttemptsSettings'

  responses:
    loginAttemptsSettings:
      description: Login attempts settings
      content:
        application/json:
          schema:
            type: object
            properties:
              settings:
                $ref: '#/components/schemas/LoginAttemptsSettings'
          examples:
            LoginAttemptsSettings:
              value:
                settings:
                  NoOfAttempts: 5
                  LoginResetTime: "15m"
                  LoginBlockingTime: "15m"
                  LoginAttemptFunctionalityEnabled: true
    loginAttemptsSettingsInvalidInput:
      description: Invalid input for login attempts settings
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            MultiError:
              value:
                errors:
                  - code: "request.invalidObject"
                    status: 400
                    title: Unable to parse request body
                  - code: "request.invalidObject"
                    status: 400
                    title: NoOfAttempts must be greater than 0
                  - code: "request.invalidObject"
                    status: 400
                    title: LoginResetTime must be a valid time duration
                  - code: "request.invalidObject"
                    status: 400
                    title: LoginBlockingTime must be a valid time duration
            NoOfAttemptsTooHigh:
              value:
                errors:
                  - code: "request.invalidObject"
                    status: 400
                    title: NoOfAttempts must be lower or equal than 255
            EmptyObject:
              value:
                errors:
                  - code: "request.invalidObject"
                    status: 400
                    title: Unable to parse request body
    userUnblockInvalidInput:
      description: Invalid input to unblock user
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            InvalidUserId:
              value:
                errors:
                  - code: "edge.invalidPathParameter"
                    status: 400
                    title: invalid userId
    errorUnauthenticated:
      description: Unauthenticated, authorization token does not exists or not starting with bearer <auth token>
      content:
        application-json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missing-auth-header:
              value:
                errors:
                  - code: "auth.missingToken"
                    status: 401
                    title: Authentication Token is missing
            invalid-auth-header:
              value:
                errors:
                  - code: "auth.unauthenticated"
                    status: 401
                    title: Authentication Token is invalid
    genericError:
      description: Something went wrong
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/errors.generic"
    errorForbidden:
      description: Unauthorized, the user doesn't have the role or the privileges to execute the action. Access denied.
      content:
        application-json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized-token:
              value:
                errors:
                  - code: "auth.unauthorizedToken"
                    status: 403
                    title: Not enough privileges to perform this action
    errorUserNotFound:
      description: The user with provided userId does not exist.
      content:
        application-json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid-userId:
              value:
                errors:
                  - code: "auth.application.userNotFound"
                    status: 404
                    title: invalid userId

  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description: Authorization token

  securitySchemes:
    API-Key:
      name: Authorization
      type: apiKey
      in: header