FOLIO Password API

openapi: 3.2.0
info:
  title: Folio Password API
  version: v1
  description: 'Operations tagged password across 4 of this provider''s published API definitions: folio-mod-login-keycloak-openapi.json, folio-mod-password-validator-openapi.json, folio-mod-login-keycloak-openapi.yml, folio-mod-password-validator-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://localhost:8081
  description: Locally deployed server
- url: /tenant/
tags:
- name: Password
paths:
  /authn/password/repeatable:
    post:
      description: Validate password for repeatability
      operationId: validatePasswordRepeatability
      tags:
      - Password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/password'
      responses:
        '200':
          description: Password validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validPassword'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Validate password repeatability
      x-summary-source: derived
    servers:
    - url: http://localhost:8081
      description: Locally deployed server
  /authn/reset-password:
    post:
      description: Resets password for user in record and deletes action record
      operationId: resetPassword
      tags:
      - Password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/passwordResetAction'
      responses:
        '201':
          description: Login response body with access/refresh tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseResetAction'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Reset password
      x-summary-source: derived
    servers:
    - url: http://localhost:8081
      description: Locally deployed server
  /authn/password-reset-action:
    post:
      description: Saves password reset action to storage
      operationId: createResetPasswordAction
      tags:
      - Password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/passwordCreateAction'
      responses:
        '201':
          description: Response to create a new password change action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseCreateAction'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Create reset password action
      x-summary-source: derived
    servers:
    - url: http://localhost:8081
      description: Locally deployed server
  /authn/password-reset-action/{actionId}:
    get:
      description: Retrieves action record by id
      operationId: getPasswordActionById
      parameters:
      - $ref: '#/components/parameters/actionId'
      tags:
      - Password
      responses:
        '200':
          description: Number of login attempts for user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/passwordCreateAction'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '404':
          $ref: '#/components/responses/entityNotFoundResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
      summary: Get password action by id
      x-summary-source: derived
    servers:
    - url: http://localhost:8081
      description: Locally deployed server
  /password/validate:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation_template'
        '400':
          description: Bad request
          content:
            text/plain:
              schema:
                type: string
                example: Bad request
        '404':
          $ref: '#/components/responses/trait_validate_404'
        '422':
          $ref: '#/components/responses/trait_validate_422'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
      operationId: validatePassword
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant-header'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/password_2'
        required: true
      tags:
      - Password
      summary: Validate password
      x-summary-source: derived
    servers:
    - url: /tenant/
  /password/check:
    post:
      description: Validate password without user id
      operationId: checkPassword
      parameters:
      - $ref: '#/components/parameters/x-okapi-tenant-header'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/password_check'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validation_template'
        '400':
          description: Bad request
          content:
            text/plain:
              schema:
                type: string
                example: Bad request
        '404':
          $ref: '#/components/responses/trait_validate_404'
        '422':
          $ref: '#/components/responses/trait_validate_422'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
                example: Internal server error
      tags:
      - Password
      summary: Check password
      x-summary-source: derived
    servers:
    - url: /tenant/
components:
  schemas:
    parameter:
      $schema: http://json-schema.org/draft-04/schema#
      id: parameter.json
      title: Key/Value Parameter Schema
      description: List of key/value parameters of an error
      type: object
      properties:
        key:
          description: Parameter key
          type: string
        value:
          description: Parameter value
          type: string
    responseResetAction:
      $schema: http://json-schema.org/draft-04/schema#
      id: passwordResetResponse.json
      title: Password Reset Action Response Schema
      description: Response entity to reset the password
      type: object
      properties:
        isNewPassword:
          description: Indicates the presence of a new password for the user
          type: boolean
    password:
      $schema: http://json-schema.org/draft-04/schema#
      id: password.json
      title: Password Schema
      description: Object with password property
      type: object
      properties:
        password:
          type: string
          description: Password
        userId:
          type: string
          description: User Id
      required:
      - password
      - userId
    passwordCreateAction:
      $schema: http://json-schema.org/draft-04/schema#
      id: passwordCreateAction.json
      title: Password Create Action Schema
      description: A password create action response
      type: object
      properties:
        id:
          description: ID of the password reset action received in the API request
          type: string
        userId:
          description: User ID to register password reset action
          type: string
        expirationTime:
          description: password expiration time
          type: string
          format: date-time
      required:
      - id
      - userId
      - expirationTime
    passwordResetAction:
      $schema: http://json-schema.org/draft-04/schema#
      id: passwordResetAction.json
      title: Password Reset Action Schema
      description: Reset password entity
      type: object
      properties:
        passwordResetActionId:
          description: Action id for reset password
          type: string
        newPassword:
          description: New password for update
          type: string
      required:
      - passwordResetActionId
      - newPassword
    errors:
      $schema: http://json-schema.org/draft-04/schema#
      id: Errors Schema
      description: A set of errors
      type: object
      properties:
        errors:
          description: List of errors
          id: errors
          type: array
          items:
            $ref: '#/components/schemas/error'
        total_records:
          description: Total number of errors
          type: integer
    errorCode:
      $schema: http://json-schema.org/draft-04/schema#
      id: errorCode.json
      title: Error Code Schema
      description: Error message code
      type: string
      enum:
      - unknown_error
      - service_error
      - validation_error
      - not_found_error
      - found_error
      - token.parse.failure
      - token.refresh.unprocessable
      - token.logout.unprocessable
      - unauthorized_error
    validPassword:
      $schema: http://json-schema.org/draft-04/schema#
      id: passwordValid.json
      title: Password validation result
      description: Password success validation result
      type: object
      properties:
        result:
          type: string
          description: Password validation result message
      required:
      - result
    error:
      $schema: http://json-schema.org/draft-04/schema#
      id: error.json
      title: Error Schema
      description: An error object
      type: object
      properties:
        message:
          type: string
          description: Error message text
        type:
          type: string
          description: Error message type
        code:
          description: Error message code
          $ref: '#/components/schemas/errorCode'
        parameters:
          description: List of key/value parameters of an error
          $ref: '#/components/schemas/parameters'
    parameters:
      $schema: http://json-schema.org/draft-04/schema#
      id: parameters.json
      title: List of Parameters Schema
      description: List of key/value parameters of an error
      type: array
      items:
        $ref: '#/components/schemas/parameter'
    responseCreateAction:
      $schema: http://json-schema.org/draft-04/schema#
      id: passwordCreateResponse.json
      title: Password Create Action Response Schema
      description: Response entity to create a new password change action
      type: object
      properties:
        passwordExists:
          description: Check if the user has an existing password or credential
          type: boolean
    parameter_2:
      $schema: http://json-schema.org/draft-04/schema#
      description: List of key/value parameters of an error
      type: object
      properties:
        key:
          description: Parameter key
          type: string
        value:
          description: Parameter value
          type: string
      additionalProperties: false
      required:
      - key
    password_2:
      $schema: http://json-schema.org/draft-04/schema#
      description: Object with password property
      type: object
      properties:
        password:
          type: string
          description: Password
        userId:
          type: string
          description: User Id
      additionalProperties: false
      required:
      - password
      - userId
    password_check:
      $schema: http://json-schema.org/draft-04/schema#
      description: Object with password property
      type: object
      properties:
        username:
          type: string
          description: Username
        password:
          type: string
          description: Password
          x-field-extra-annotation: '@jakarta.validation.constraints.NotEmpty(message = "password.empty")'
      additionalProperties: false
      required:
      - username
      - password
    error_2:
      $schema: http://json-schema.org/draft-04/schema#
      description: An error
      type: object
      properties:
        message:
          type: string
          description: Error message text
        type:
          type: string
          description: Error message type
        code:
          type: string
          description: Error message code
        parameters:
          type: object
          description: Error message parameters
          $ref: '#/components/schemas/parameters_2'
      additionalProperties: false
      required:
      - message
    errors_2:
      $schema: http://json-schema.org/draft-04/schema#
      description: A set of errors
      type: object
      properties:
        errors:
          description: List of errors
          id: errors
          type: array
          items:
            type: object
            $ref: '#/components/schemas/error_2'
        total_records:
          description: Total number of errors
          type: integer
      additionalProperties: false
    parameters_2:
      $schema: http://json-schema.org/draft-04/schema#
      description: List of key/value parameters of an error
      type: array
      items:
        type: object
        $ref: '#/components/schemas/parameter_2'
      additionalProperties: false
    validation_template:
      $schema: http://json-schema.org/draft-04/schema#
      description: Validation Result Template
      type: object
      properties:
        result:
          type: string
          description: validation result
        messages:
          type: array
          items:
            type: string
          description: validation messages
    parameter_3:
      $schema: http://json-schema.org/draft-04/schema#
      description: List of key/value parameters of an error
      type: object
      properties:
        key:
          description: Parameter key
          type: string
        value:
          description: Parameter value
          type: string
      additionalProperties: false
      required:
      - key
    password_3:
      $schema: http://json-schema.org/draft-04/schema#
      description: Object with password property
      type: object
      properties:
        password:
          type: string
          description: Password
        userId:
          type: string
          description: User Id
      additionalProperties: false
      required:
      - password
      - userId
    error_3:
      $schema: http://json-schema.org/draft-04/schema#
      description: An error
      type: object
      properties:
        message:
          type: string
          description: Error message text
        type:
          type: string
          description: Error message type
        code:
          type: string
          description: Error message code
        parameters:
          type: object
          description: Error message parameters
          $ref: '#/components/schemas/parameters_3'
      additionalProperties: false
      required:
      - message
    errors_3:
      $schema: http://json-schema.org/draft-04/schema#
      description: A set of errors
      type: object
      properties:
        errors:
          description: List of errors
          id: errors
          type: array
          items:
            type: object
            $ref: '#/components/schemas/error_3'
        total_records:
          description: Total number of errors
          type: integer
      additionalProperties: false
    parameters_3:
      $schema: http://json-schema.org/draft-04/schema#
      description: List of key/value parameters of an error
      type: array
      items:
        type: object
        $ref: '#/components/schemas/parameter_3'
      additionalProperties: false
  responses:
    entityNotFoundResponse:
      description: Error response if entity is not found by id (in json format)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
    internalServerErrorResponse:
      description: Error response for unhandled or critical server exceptions, e.g. NullPointerException.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
    badRequestResponse:
      description: Error response in JSON format for validation errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
    trait_validate_404:
      description: Not found error
      content:
        application/json:
          example: examples/error.sample
          schema:
            $ref: '#/components/schemas/error_2'
    trait_validate_422:
      description: Validation errors
      content:
        application/json:
          example: examples/errors.sample
          schema:
            $ref: '#/components/schemas/errors_2'
    trait_validate_404_2:
      description: Not found error
      content:
        application/json:
          example: examples/error.sample
          schema:
            $ref: '#/components/schemas/error_3'
    trait_validate_422_2:
      description: Validation errors
      content:
        application/json:
          example: examples/errors.sample
          schema:
            $ref: '#/components/schemas/errors_3'
  parameters:
    actionId:
      in: path
      required: true
      name: actionId
      description: Action Identifier
      schema:
        type: string
    x-okapi-tenant-header:
      name: x-okapi-tenant
      in: header
      description: x-okapi-tenant header value
      required: false
      schema:
        type: string
x-refined-from:
- folio-mod-login-keycloak-openapi.json
- folio-mod-password-validator-openapi.json
- folio-mod-login-keycloak-openapi.yml
- folio-mod-password-validator-openapi.yml