openapi: 3.2.0
info:
  contact:
    name: Koha Development Team
    url: https://koha-community.org/
  description: '## Background


    The API supports two sets of endpoints, one targetted at library staff and the other at at library users.'
  license:
    name: GPL v3,
    url: http://www.gnu.org/licenses/gpl.txt
  title: Koha REST 2fa API
  version: '1'
servers:
- url: https://libserv.iitk.ac.in/api/v1
  description: PKK Library Koha REST API (production)
tags:
- description: Handle two factor authentication flows
  name: 2 FA
  x-displayName: Two factor authentication
paths:
  /auth/otp/token_delivery:
    post:
      tags:
      - 2 FA
      summary: Send OTP token for second step authentication
      operationId: send_otp_token
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                  token_type:
                    type: string
                type: object
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '401':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '404':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
        '500':
          description: 'Internal server error. Possible `error_code` attribute values:


            * `internal_server_error`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '501':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
  /auth/two-factor/registration:
    post:
      tags:
      - 2 FA
      summary: Generate a secret
      operationId: TwoFactorRegister
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  issuer:
                    type: string
                  key_id:
                    type: string
                  qr_code:
                    type: string
                  secret32:
                    type: string
                type: object
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '401':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '404':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
        '500':
          description: 'Internal server error. Possible `error_code` attribute values:


            * `internal_server_error`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '501':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      x-operation-id-source: normalized
      x-operation-id-original: Two factor register
  /auth/two-factor/registration/verification:
    post:
      tags:
      - 2 FA
      summary: Verify two-factor registration
      operationId: TwoFactorRegisterVerification
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                secret32:
                  type: string
                pin_code:
                  type: string
      responses:
        '204':
          description: OK
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '404':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
        '500':
          description: 'Internal server error. Possible `error_code` attribute values:


            * `internal_server_error`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_yaml'
        '501':
          description: Default response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      x-operation-id-source: normalized
      x-operation-id-original: Two factor register verification
components:
  schemas:
    DefaultResponse:
      properties:
        errors:
          items:
            properties:
              message:
                type: string
              path:
                type: string
            required:
            - message
            type: object
          type: array
      required:
      - errors
      type: object
    error_yaml:
      additionalProperties: true
      properties:
        error:
          description: Error message
          type: string
        error_code:
          description: Error code
          type: string
      type: object