2fauth-api-v1.7.0.yaml

openapi: 3.1.0
info:
  title: 2FAuth API
  version: 1.7.0
  description: |-
    This is the definition (following OpenAPI 3.1 specification) of the REST API of [2FAuth](https://github.com/Bubka/2FAuth), a web app to manage your Two-Factor Authentication (2FA) accounts and generate their security passwords.

    The API is available once you installed 2FAuth on your server.
  contact:
    name: Bubka
    url: 'https://github.com/Bubka'
    email: contact@2fauth.app
  license:
    name: AGPL-3.0
    url: 'https://www.gnu.org/licenses/agpl-3.0.en.html'
servers:
  - url: 'https://demo.2fauth.app'
    description: Demo server
paths:
  /api/v1/twofaccounts:
    get:
      summary: Get all 2FA accounts
      tags:
        - twofaccounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountCollection'
              examples:
                Example without secret:
                  value:
                    - id: 1
                      group_id: 1
                      service: MySite
                      account: john.doe
                      icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                      otp_type: totp
                      digits: 6
                      algorithm: sha1
                      period: 30
                      counter: null
                    - id: 2
                      group_id: 1
                      service: MyOtherSite
                      account: john.doe
                      icon: 1pawLLuMx4bOQkrZxM5CIQyFtVq25dtgMkU3rtST.png
                      otp_type: hotp
                      digits: 8
                      algorithm: sha1
                      period: null
                      counter: 15
                Example with secret:
                  value:
                    - id: 1
                      group_id: 1
                      service: MySite
                      account: john.doe
                      icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                      otp_type: totp
                      digits: 6
                      algorithm: sha1
                      secret: GJTGC5LUNA
                      period: 30
                      counter: null
                    - id: 2
                      group_id: 1
                      service: MyOtherSite
                      account: john.doe
                      icon: 1pawLLuMx4bOQkrZxM5CIQyFtVq25dtgMkU3rtST.png
                      otp_type: hotp
                      digits: 8
                      algorithm: sha1
                      secret: QD5TG6UUJ89F44GV
                      period: null
                      counter: 15
                Example with otp object:
                  value:
                    - id: 1
                      group_id: 1
                      service: MySite
                      account: john.doe
                      icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                      otp_type: totp
                      digits: 6
                      algorithm: sha1
                      period: 30
                      counter: null
                      otp:
                        password: '045698'
                        generated_at: 1701788671
                    - id: 2
                      group_id: 1
                      service: MyOtherSite
                      account: john.doe
                      icon: 1pawLLuMx4bOQkrZxM5CIQyFtVq25dtgMkU3rtST.png
                      otp_type: hotp
                      digits: 8
                      algorithm: sha1
                      period: null
                      counter: 15
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: get-twofaccounts
      description: Find all 2FA accounts of the authenticated user
      parameters:
        - $ref: '#/components/parameters/withSecret'
        - schema:
            type: string
            example: '1,20,9,456'
          in: query
          name: ids
          description: Comma-separated list of ids to filter returned 2FA accounts
        - schema:
            type: boolean
          in: query
          name: withOtp
          description: Set to true (or 1) to append an OTP object to the returned 2FA accounts of type TOTP
    parameters: []
    post:
      summary: Create 2FA account
      tags:
        - twofaccounts
      operationId: post-twofaccounts
      description: Creates a new 2FA account for the authenticated user
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/2FAccountStore'
                - $ref: '#/components/schemas/OtpauthUri'
            examples:
              Example with properties:
                value:
                  service: MySite
                  account: john.doe
                  icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                  otp_type: totp
                  digits: 6
                  algorithm: sha1
                  secret: GJTGC5LUNA
                  period: 30
                  counter: null
              Example with URI:
                value:
                  uri: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite&period=30&algorithm=sha1&digits=6&image=https://www.example.com/image.png'
        description: |-
          This endpoint accepts 2 different body schemas to create a new 2FA account:
          - A full JSON object with some properties
          - An URI based on the otpauth format
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountRead'
              examples:
                Example:
                  value:
                    id: 1
                    group_id: 1
                    service: MySite
                    account: john.doe
                    icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                    otp_type: totp
                    secret: GJTGC5LUNA
                    digits: 6
                    algorithm: sha1
                    period: 30
                    counter: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters: []
    delete:
      summary: Mass delete 2FA accounts
      operationId: delete-twofaccounts
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
        - twofaccounts
      description: |-
        Mass deletes 2FA accounts of the authenticated user matching the IDs passed as query parameter.

        A `204 — No Content` response will be returned even if some resources no longer exist before delete.
      parameters:
        - $ref: '#/components/parameters/ids'
  '/api/v1/twofaccounts/{id}':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Find 2FA account by ID
      tags:
        - twofaccounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountRead'
              examples:
                Example without secret:
                  value:
                    id: 1
                    group_id: 1
                    service: MySite
                    account: john.doe
                    icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                    otp_type: totp
                    digits: 6
                    algorithm: sha1
                    period: 30
                    counter: null
                Example with secret:
                  value:
                    id: 1
                    group_id: 1
                    service: MySite
                    account: john.doe
                    icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                    otp_type: totp
                    secret: GJTGC5LUNA
                    digits: 6
                    algorithm: sha1
                    period: 30
                    counter: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-twofaccounts-id
      description: Returns a single 2FA account of the authenticated user
      parameters:
        - $ref: '#/components/parameters/withSecret'
    put:
      summary: Update 2FA account
      operationId: put-twofaccounts-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountRead'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: Updates a 2FA account of the authenticated user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/2FAccountUpdate'
            examples:
              Example:
                value:
                  service: MySite
                  account: john.doe
                  icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                  otp_type: totp
                  digits: 6
                  algorithm: sha1
                  secret: GJTGC5LUNA
                  period: 30
      tags:
        - twofaccounts
    delete:
      summary: Delete 2FA account
      operationId: delete-twofaccounts-id
      responses:
        '204':
          description: No Content
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - twofaccounts
      description: Deletes a 2FA account of the authenticated user
  '/api/v1/twofaccounts/{id}/qrcode':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Encode a 2FA account in a QR code
      tags:
        - qrcode
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    qrcode: 'data:image/png;base64,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'
                properties:
                  qrcode:
                    type: string
                    example: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASgAAAEoCAIAAABkZftOAAAABnRSTlMA/wD/AP83WBt9AAAACXBIWXMAAA7EAAAOxAGVKw4bAAAGFUlEQVR4nO3dsbJbJxRA0SiT//9lp7BbipOBbHhaq37WlWTtoTgDfH79+vUX8P/6u34D8I2EBwHhQUB4EBAeBIQHAeFBQHgQEB4EhAcB4UFAeBAQHgSEBwHhQeCf6T/4fD4n3sd2p/cZVt/D6nNN38/0+zn9+rueW5l+XiseBIQHAeFBQHgQEB4EhAcB4UFgPMdbqc7n3DXneWUOtnqd09//rvnhrvf/+u/NigcB4UFAeBAQHgSEBwHhQUB4ENg2x1vZNfeo5lRTp+dst+0zvG3e+MrvzYoHAeFBQHgQEB4EhAcB4UFAeBA4Pse7TTVfOm3X/G3XvruVn/r9T1nxICA8CAgPAsKDgPAgIDwICA8CXzfHWzl93mO1T2/13Oq+O36z4kFAeBAQHgSEBwHhQUB4EBAeBI7P8W6b/5w+P3P63Ol8r7rH7/Tn3eW239uKFQ8CwoOA8CAgPAgIDwLCg4DwILBtjnd6PrPLrrlZNadaOb0P8LbP+8rvbcWKBwHhQUB4EBAeBIQHAeFBQHgQGM/xXtnvtHJ6P57v57fT88PXWfEgIDwICA8CwoOA8CAgPAgIDwLjOV51r9qu/Vev7Lubvv7pfYa7nH7uK/f+WfEgIDwICA8CwoOA8CAgPAgIDwLH78dbqc57rOaBu17/dbvu69ulmvtZ8SAgPAgIDwLCg4DwICA8CAgPAp9dc5Xb5jOn993d9nmnqjnkK68/fe6UFQ8CwoOA8CAgPAgIDwLCg4DwIJDtx1up5m+n53W37a97ZT5ZzetOs+JBQHgQEB4EhAcB4UFAeBAQHgTGc7xd86jT52eenv9U99et3DYnnLrte5ieyzp9rhUPAsKDgPAgIDwICA8CwoOA8CAwPlfztNP72W6bC02fW80td6nmddX3v2LFg4DwICA8CAgPAsKDgPAgIDwIXDfHm7ptTjV1el40VZ1HOn0/K9V8b8qKBwHhQUB4EBAeBIQHAeFBQHgQGJ+redu+pm+7T++2+/eqfYOn9x/ajwc/kPAgIDwICA8CwoOA8CAgPAhsux9v131ir8+1TrvtvM1d9wSuVPcxnn4dKx4EhAcB4UFAeBAQHgSEBwHhQWB8rmY1l1s5fX7j6e9n6rb78W6bK75ynqcVDwLCg4DwICA8CAgPAsKDgPAgsO1+vJ96LuVtc8Xpc287r/IVztWEH0h4EBAeBIQHAeFBQHgQEB4Etu3Hm3p97vT6nHDltv1+U7ftn1yx4kFAeBAQHgSEBwHhQUB4EBAeBMb3463sujdv6vW52dTpOedtn/f0nLn6fqx4EBAeBIQHAeFBQHgQEB4EhAeBbXO8qWrf1Onn3rY/cNffT1+nuidw5bb5pBUPAsKDgPAgIDwICA8CwoOA8CCQzfFWpvOZ6lzH284XvW0f2ulzR18553PFigcB4UFAeBAQHgSEBwHhQUB4EDg+xzs9b7ltXnR6v99tc61XzkedPnf699P/dyseBIQHAeFBQHgQEB4EhAcB4UHgc/r+salX5mDOh/xvbtsvV32fVjwICA8CwoOA8CAgPAgIDwLCg8B4P95tc6TT87TqHr9dTs8JT++rnKr2H9qPBw8QHgSEBwHhQUB4EBAeBIQHgfEc77b9VCvV3Oynzjmnr1+dt7nL6eda8SAgPAgIDwLCg4DwICA8CAgPAtvux3tlv9lp0/nPdA52et/gyvT1d833dv2uqvsDV6x4EBAeBIQHAeFBQHgQEB4EhAeBbXO8ldvOXazmZivVeZ675lrVXHEX9+PBFxEeBIQHAeFBQHgQEB4EhAeB43O8b7Nr39rKK3Ozan5bzWOnrHgQEB4EhAcB4UFAeBAQHgSEBwFzvD9O76/bZbqP7vR5mNUccuq2/ZNWPAgIDwLCg4DwICA8CAgPAsKDwPE5XrXfaeW2edT0dV7/+9vmkNPX2fV7tuJBQHgQEB4EhAcB4UFAeBAQHgS2zfGq+8122fX+d821dj13qno/1bz39FxxxYoHAeFBQHgQEB4EhAcB4UFAeBD43LZfDr6BFQ8CwoOA8CAgPAgIDwLCg4DwICA8CAgPAsKDgPAgIDwICA8CwoOA8CDwLzF4/0kW8W0CAAAAAElFTkSuQmCC'
                required:
                  - qrcode
              examples:
                Example:
                  value:
                    qrcode: 'data:image/png;base64,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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-twofaccounts-id-qrcode
      description: Returns a QR code that represents a 2FA account owned by the authenticated user
  '/api/v1/twofaccounts/{id}/otp':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Get a One-Time password
      tags:
        - one-time password
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Otp'
              examples:
                Example for TOTP:
                  value:
                    password: '225897'
                    otp_type: totp
                    generated_at: 1631304659
                    period: 30
                Example for HOTP:
                  value:
                    password: '225897'
                    otp_type: hotp
                    counter: 5
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-twofaccounts-id-otp
      description: Returns a fresh One-Time Password for the 2FA account of the authenticated user matching the specified ID
  /api/v1/twofaccounts/otp:
    parameters: []
    post:
      summary: Get a One-Time password
      tags:
        - one-time password
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/2FAccountStore'
                - $ref: '#/components/schemas/OtpauthUri'
            examples: {}
        description: |-
          This endpoint accepts 2 different body schemas to generate a One-Time Password:
          - A JSON object with all properties to define a 2FA account
          - An otpauth URI
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Otp'
              examples:
                Eexample for TOTP:
                  value:
                    password: '225897'
                    otp_type: totp
                    generated_at: 1631304659
                    period: 30
                Example for HOTP:
                  value:
                    password: '225897'
                    otp_type: hotp
                    counter: 5
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      operationId: post-twofaccounts-otp
      description: Returns a fresh One-Time password with related parameters for account defined by the provided data
  /api/v1/twofaccounts/migration:
    post:
      summary: Convert a migration resource
      operationId: post-twofaccounts-migration
      responses:
        '200':
          description: |-
            Ok

            > 2FA accounts are always returned with an ID between -2 and 0:
            > - `id: -2` means the returned account does not reflect the exact submited data because those data are invalid or unreadable. You should not used this account definition.
            > - `id: -1` means the returned account already exists in the authenticated user accounts in database. It's a valid account but probably useless you should discard.
            > - `id: 0` means the returned account is successfully migrated and is valid
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/2FAccountMigrated'
              examples:
                Example:
                  value:
                    - id: 0
                      group_id: null
                      service: MySite
                      account: john.doe
                      icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                      otp_type: totp
                      secret: GJTGC5LUNA
                      digits: 6
                      algorithm: sha1
                      period: 30
                      counter: null
                    - id: -1
                      group_id: null
                      service: MySite
                      account: john.doe
                      icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                      otp_type: totp
                      secret: GJTGC5LUNA
                      digits: 6
                      algorithm: sha1
                      period: 30
                      counter: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      description: |-
        Use this endpoint to convert exported 2FAs from another 2FA app to a list of 2FA resources you can POST using the API to create new 2FA accounts.

        > This endpoint does not store anything in database.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payload:
                  type: string
                  description: The migration payload
              required:
                - payload
            examples:
              Example for Google Authenticator:
                value:
                  payload: 'otpauth-migration://offline?data=w0SnrWITY/RFhILYWNjb3VudF9iaXMaC3NlcnZpY2VfYmlzIAEoATACEAEYASAA'
                  withSecret: true
              Example for a list of otpauth URIs:
                value:
                  payload: |-
                    otpauth://totp/dropbox:john?secret=T5THFHVVRSDF4AWS
                    otpauth://totp/dropbox:jane?secret=A4GRFHVVRBGY7UIW
                  withSecret: true
              Example for a JSON payload:
                value:
                  payload: |-
                    {
                    "version":1,
                    "header":{
                    "slots":null,
                    "params":null
                    },
                    "db":{
                    "version":2,
                    "entries":[
                    {
                    "type":"totp",
                    "uuid":"5be1c189-240d-5fe1-930b-a78xb669zd86",
                    "name":"JohnDOE",
                    "issuer":"Facebook",
                    "note":"",
                    "icon":null,
                    "info":{
                    "secret":"A4GRFTVVRBGY7UIW",
                    "algo":"SHA1",
                    "digits":6,
                    "period":30,
                    "counter":30
                    }
                    }
                    ]
                    }
                    }
                  withSecret: true
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The migration file
              required:
                - file
            examples:
              Example:
                value:
                  file: string
        description: |-
          This endpoint accepts 2 different body schemas:
          - A JSON object which contain a migration payload. Typically the content of an export file or the decoded content of a QR code.
          - A multi-part/form-data to submit an export file directly
      tags:
        - twofaccounts
      parameters:
        - $ref: '#/components/parameters/withSecret'
    parameters: []
  /api/v1/twofaccounts/preview:
    post:
      summary: Preview 2FA account
      operationId: post-twofaccounts-preview
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountRead'
              examples:
                Example:
                  value:
                    id: 1
                    group_id: 1
                    service: MySite
                    account: john.doe
                    icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                    otp_type: totp
                    secret: GJTGC5LUNA
                    digits: 6
                    algorithm: sha1
                    period: 30
                    counter: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: |-
        Use this endpoint to preview a 2FA account described by an otpauth URI.
        It works exactly as if you POSTed an URI to create a 2FA account except it does not save anything in database.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtpauthUri'
            examples:
              Example:
                value:
                  uri: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite&period=30&algorithm=sha1&digits=6&image=https://www.example.com/image.png'
        description: ''
      tags:
        - twofaccounts
    parameters: []
  /api/v1/twofaccounts/reorder:
    post:
      summary: Save order of the 2FA accounts collection
      operationId: post-twofaccounts-reorder
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: Saves the order of the 2FA accounts of the authenticated user. This allows to always serve the 2FA accounts collection sorted in a user defined order.
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              properties:
                orderedIds:
                  type: array
                  uniqueItems: true
                  description: An array of 2FA account IDs ordered in the wished order
                  items:
                    type: integer
              required:
                - orderedIds
            examples:
              Example:
                value:
                  orderedIds:
                    - 3
                    - 1
                    - 4
                    - 2
        description: ''
      tags:
        - twofaccounts
    parameters: []
  /api/v1/twofaccounts/withdraw:
    patch:
      summary: Withdraw accounts from groups
      operationId: patch-twofaccounts-withdraw
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: Removes a list of 2FA accounts of the authenticated user from any group
      parameters:
        - $ref: '#/components/parameters/ids'
      tags:
        - twofaccounts
    parameters: []
  /api/v1/twofaccounts/export:
    get:
      summary: Export 2FA accounts
      operationId: get-twofaccounts-export
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  app:
                    type: string
                    description: The export supplier
                  schema:
                    type: integer
                    example: 1
                    description: Schema version of the migration. Only available when data are exported using the 2FAuth format.
                  datetime:
                    type: string
                    format: date-time
                    example: '2023-03-22T11:11:33.299209Z'
                    description: Date and time the migration has been generated
                  data:
                    anyOf:
                      - items:
                          $ref: '#/components/schemas/2FAccountExport'
                      - items:
                          $ref: '#/components/schemas/2FAccountExportOtpauthURI'
                    type: array
                required:
                  - app
                  - datetime
                  - data
              examples:
                Example (2FAuth format):
                  value:
                    app: 2fauth_v3.4.2
                    schema: 1
                    datetime: '2023-03-22T11:11:33.299209Z'
                    data:
                      - service: MySite
                        account: john.doe
                        icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                        icon_mime: image/png
                        icon_file: iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMATSSZLxZNZ7LxhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMKW//A0lifIQSJgQuAAAAAElFTkSuQmCC
                        otp_type: totp
                        secret: GJTGC5LUNA
                        digits: 6
                        algorithm: sha1
                        period: 30
                        counter: null
                        legacy_uri: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite'
                      - service: AnotherSite
                        account: jane.doe
                        icon: dfGdfGretDfhYUTzZEdcDtghfdgdfg.png
                        icon_mime: image/png
                        icon_file: iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMATSSZLxZNZ7LxhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMKW//A0lifIQSJgQuAAAAAElFTkSuQmCC
                        otp_type: hotp
                        secret: GUKLZ8DCTA
                        digits: 6
                        algorithm: sha1
                        period: null
                        counter: 5
                        legacy_uri: 'otpauth://hotp/MySite:jane.doe?secret=GUKLZ8DCTA&issuer=AnotherSite'
                Example (otpauth URIs):
                  value:
                    app: 2fauth_v3.4.2
                    datetime: '2023-03-22T11:11:33.299209Z'
                    data:
                      - uri: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: Exports a list of 2FA accounts owned by the authenticated user.
      parameters:
        - $ref: '#/components/parameters/ids'
        - schema:
            type: boolean
          in: query
          name: otpauth
          description: Force data to be exported as a list of otpauth URIs instead of the 2FAuth json format
      tags:
        - twofaccounts
    parameters: []
  /api/v1/groups:
    get:
      summary: Get all groups
      tags:
        - groups
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupCollection'
              examples:
                Example:
                  value:
                    - id: 0
                      name: All
                      twofaccounts_count: 9
                    - id: 1
                      name: Social networks
                      twofaccounts_count: 4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: get-groups
      description: Find all groups of the authenticated user
    post:
      summary: Create Group
      operationId: post-groups
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupRead'
              examples:
                Example:
                  value:
                    id: 1
                    name: Social networks
                    twofaccounts_count: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupStore'
            examples:
              Example:
                value:
                  name: Social networks
      tags:
        - groups
      description: Creates a new group for the authenticated user
    parameters: []
  '/api/v1/groups/{id}':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Find group by ID
      tags:
        - groups
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupRead'
              examples:
                Example:
                  value:
                    id: 1
                    name: Social networks
                    twofaccounts_count: 4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-groups-id
      description: Returns a single group of the authenticated user
    put:
      summary: Update group
      operationId: put-groups-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupRead'
              examples:
                Example:
                  value:
                    id: 1
                    name: Social networks
                    twofaccounts_count: 4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: Updates a group of the authenticated user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupStore'
            examples:
              Example:
                value:
                  name: Social networks
      tags:
        - groups
    delete:
      summary: Delete group
      operationId: delete-groups-id
      description: Deletes a group of the authenticated user. This will not delete any assigned 2FA accounts.
      responses:
        '204':
          description: No Content
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - groups
  '/api/v1/groups/{id}/assign':
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      summary: Add 2FA accounts to a group
      tags:
        - groups
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupRead'
              examples:
                Example:
                  value:
                    id: 1
                    name: Social networks
                    twofaccounts_count: 4
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
      operationId: post-groups-id-assign
      description: Adds a list of 2FA accounts to a group of the authenticated user. An account previously assigned to another group will be removed from its former group. The 2FA accounts must be owned by the authenticated user.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  description: An array of 2FA account IDs
                  items:
                    type: integer
              required:
                - ids
            examples:
              Example:
                value:
                  ids:
                    - 1
                    - 5
                    - 9
  '/api/v1/groups/{id}/twofaccounts':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Get all 2FA accounts of a group
      tags:
        - groups
        - twofaccounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountCollection'
              examples:
                Example without secret:
                  value:
                    - id: 1
                      group_id: 1
                      service: MySite
                      account: john.doe
                      icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                      otp_type: totp
                      digits: 6
                      algorithm: sha1
                      period: 30
                      counter: null
                    - id: 2
                      group_id: 1
                      service: MyOtherSite
                      account: john.doe
                      icon: 1pawLLuMx4bOQkrZxM5CIQyFtVq25dtgMkU3rtST.png
                      otp_type: hotp
                      digits: 8
                      algorithm: sha1
                      period: null
                      counter: 15
                Example with secret:
                  value:
                    - id: 1
                      group_id: 1
                      service: MySite
                      account: john.doe
                      icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                      otp_type: totp
                      digits: 6
                      algorithm: sha1
                      secret: GJTGC5LUNA
                      period: 30
                      counter: null
                    - id: 2
                      group_id: 1
                      service: MyOtherSite
                      account: john.doe
                      icon: 1pawLLuMx4bOQkrZxM5CIQyFtVq25dtgMkU3rtST.png
                      otp_type: hotp
                      digits: 8
                      algorithm: sha1
                      secret: QD5TG6UUJ89F44GV
                      period: null
                      counter: 15
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-groups-id-twofaccounts
      description: Finds all existing 2FA accounts assigned to a group of the authenticated user
      parameters:
        - $ref: '#/components/parameters/withSecret'
  /api/v1/icons:
    post:
      summary: Upload an icon
      tags:
        - icons
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    filename: wspRWRSCo62kY76JFquzqq8Y2jJO1iEowZ3JsMCw.png
                properties:
                  filename:
                    type: string
                    example: wspRWRSCo62kY76JFquzqq8Y2jJO1iEowZ3JsMCw.png
                    description: The icon filename
                required:
                  - filename
              examples:
                Example:
                  value:
                    filename: wspRWRSCo62kY76JFquzqq8Y2jJO1iEowZ3JsMCw.png
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: post-icons
      description: 'Use this endpoint to upload and store an icon (an image file: jpeg, png, bmp, gif, svg, or webp) on the server'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              format: binary
              properties:
                icon:
                  type: string
                  description: An image file
                  format: binary
              required:
                - icon
            examples:
              Example:
                value:
                  icon: string
        description: ''
    parameters: []
  '/api/v1/icons/{filename}':
    parameters:
      - schema:
          type: string
          example: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
        name: filename
        in: path
        required: true
        description: Filename (with extension) of the icon file to delete from the server
    delete:
      summary: Delete an icon
      operationId: delete-icons-filename
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: Deletes an icon from the server
      tags:
        - icons
  /api/v1/qrcode/decode:
    post:
      summary: Decode a QR code
      operationId: post-qrcode-decode
      description: |-
        Use this endpoint to decode a QR code (an image file: jpeg, png, bmp, gif, svg, or webp).
        The QR code is expected to be a 2FA resource but any QR code will be decoded.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              format: binary
              properties:
                qrcode:
                  type: string
                  description: A QR code image file
                  format: binary
              required:
                - qrcode
            examples:
              Example:
                value:
                  qrcode: string
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    data: 'otpauth://totp/Mysite:john.doe?issuer=Mysite&secret=J52HAU3FMNZGK5A'
                properties:
                  data:
                    type: string
                    example: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA'
                    description: The data encoded in the QR code
                required:
                  - data
              examples:
                Example:
                  value:
                    data: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: ''
                type: object
                x-examples:
                  example-1:
                    message: not a valid QR code
                properties:
                  message:
                    type: string
                    description: An information message
                required:
                  - message
              examples:
                Example:
                  value:
                    message: not a valid QR code
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - qrcode
    parameters: []
  /api/v1/settings:
    get:
      summary: Get all settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingCollection'
              examples:
                Example:
                  value:
                    - key: useEncryption
                      value: false
                    - key: checkForUpdate
                      value: true
                    - key: yourCustomSetting
                      value: your custom value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: get-settings
      description: |-
        List all application settings. This includes 2FAuth native settings and possible additional admin-defined settings.

        Settings endpoints are restricted to user with an `Administrator` role.
      tags:
        - settings
      x-badges:
        - color: orange
          label: admin
    parameters: []
    post:
      summary: Create custom setting
      operationId: post-settings
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setting'
              examples:
                Example:
                  value:
                    key: displayMode
                    value: grid
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: |-
        Creates a new custom application setting. You are free to use this endpoint to store any data you need to administrate your own app.

        Settings endpoints are restricted to user with an `Administrator` role.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Setting'
            examples:
              Example:
                value:
                  key: useEncryption
                  value: true
        description: ''
      tags:
        - settings
      x-badges:
        - color: orange
          label: admin
  '/api/v1/settings/{name}':
    parameters:
      - $ref: '#/components/parameters/name'
    get:
      summary: Find setting by name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setting'
              examples:
                Example:
                  value:
                    key: checkForUpdate
                    value: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-settings-name
      description: |-
        Returns a single application setting, whether it is a native 2FAuth setting or a custom setting.

        Settings endpoints are restricted to user with an `Administrator` role.
      tags:
        - settings
      x-badges:
        - color: orange
          label: admin
    put:
      summary: Update setting
      operationId: put-settings-name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Setting'
              examples:
                Example:
                  value:
                    key: displayMode
                    value: grid
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: |-
        Updates an application setting, whether it is a native 2FAuth setting or a custom setting. Will create the setting if it does not exist.

        Settings endpoints are restricted to user with an `Administrator` role.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: string
                  description: Value of the setting
                  example: myValue
              required:
                - value
            examples:
              Example:
                value:
                  value: myValue
      tags:
        - settings
      x-badges:
        - color: orange
          label: admin
    delete:
      summary: Delete custom setting
      operationId: delete-settings-name
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: |-
        Deletes a custom application setting.

        Settings endpoints are restricted to user with an `Administrator` role.
      tags:
        - settings
      x-badges:
        - color: orange
          label: admin
  /api/v1/user:
    get:
      summary: Get user
      tags:
        - user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRead'
              examples:
                Example:
                  value:
                    id: 0
                    name: John
                    email: user@example.com
                    oauth_provider: string
                    preferences:
                      preference_name_1: string
                      preference_name_2: 0
                      preference_name_3: true
                    is_admin: false
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: get-user
      security: []
      description: Use this endpoint to get informations about the authenticated user.
    parameters: []
  /api/v1/user/name:
    get:
      summary: Get user name
      tags:
        - user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type:
                      - string
                      - 'null'
                    description: Username
                    example: John
                required:
                  - name
              examples:
                Example when a user exist:
                  value:
                    name: John
                Example when no user exist:
                  value:
                    name: null
      operationId: get-user-name
      security: []
      description: |-
        This endpoint is deprecated since API v1.1.0

        Use this endpoint to check if a registered user exists by getting its name, null otherwise.
      deprecated: true
    parameters: []
  /api/v1/user/preferences:
    get:
      summary: Get all user preferences
      tags:
        - user preference
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPreferenceCollection'
              examples:
                Example:
                  value:
                    - key: displayMode
                      value: grid
                      locked: true
                    - key: showTokenAsDot
                      value: true
                      locked: false
                    - key: kickUserAfter
                      value: 5
                      locked: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: get-user-preferences
      description: List all preferences of the authenticated user.
    parameters: []
  '/api/v1/user/preferences/{name}':
    parameters:
      - $ref: '#/components/parameters/name'
    get:
      summary: Find user preference by name
      tags:
        - user preference
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPreference'
              examples:
                Example:
                  value:
                    key: displayMode
                    value: grid
                    locked: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-user-preferences-name
      description: Returns a single preference of the authenticated user
    put:
      summary: Update user preference
      operationId: put-user-preferences-name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPreference'
              examples:
                Example:
                  value:
                    key: displayMode
                    value: grid
                    locked: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
      tags:
        - user preference
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: string
                  description: Value of the user preference
                  example: myValue
              required:
                - value
            examples:
              Example:
                value:
                  value: myValue
      description: Updates a preference of the authenticated user.
  /api/v1/users:
    get:
      summary: Get all registered users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagerCollection'
              examples:
                Example:
                  value:
                    - id: 0
                      name: John
                      email: user@example.com
                      oauth_provider: string
                      preferences:
                        preference_name_1: string
                        preference_name_2: 0
                        preference_name_3: true
                      is_admin: false
                      twofaccounts_count: 5
                      last_seen_at: Yesterday
                      created_at: string
                    - id: 1
                      name: Jane
                      email: jane@example.com
                      oauth_provider: null
                      preferences:
                        preference_name_1: string
                        preference_name_2: 0
                        preference_name_3: true
                      is_admin: true
                      twofaccounts_count: 10
                      last_seen_at: Today
                      created_at: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: get-users
      description: |-
        Find all registered users.

        `/users` endpoints are restricted to user with an `Administrator` role.
      parameters: []
      tags:
        - users
      x-badges:
        - color: orange
          label: admin
    parameters: []
    post:
      summary: Create user
      operationId: post-users
      description: |-
        Registers a new user.

        `/users` endpoints are restricted to user with an `Administrator` role.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagerRead'
              examples:
                Example:
                  value:
                    id: 0
                    name: John
                    email: johndoe@example.com
                    oauth_provider: null
                    preferences:
                      preference_name_1: string
                      preference_name_2: 0
                      preference_name_3: true
                    is_admin: true
                    twofaccounts_count: 0
                    last_seen_at: string
                    created_at: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      parameters: []
      x-badges:
        - color: orange
          label: admin
      tags:
        - users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserStore'
            examples:
              Example:
                value:
                  name: john doe
                  email: johndoe@example.com
                  password: P4sSw0rD
                  password_confirmation: P4sSw0rD
                  is_admin: true
  '/api/v1/users/{id}':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Find user by ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagerRead'
              examples:
                Example:
                  value:
                    id: 0
                    name: John
                    email: user@example.com
                    oauth_provider: string
                    preferences:
                      preference_name_1: string
                      preference_name_2: 0
                      preference_name_3: true
                    is_admin: false
                    twofaccounts_count: 0
                    last_seen_at: string
                    created_at: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-users-id
      description: |-
        Returns a single registered user.

        `/users` endpoints are restricted to user with an `Administrator` role.
      parameters: []
      tags:
        - users
      x-badges:
        - color: orange
          label: admin
    delete:
      summary: Delete user
      operationId: delete-users-id
      responses:
        '204':
          description: No Content
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: |-
        Deletes a registered user.

        `/users` endpoints are restricted to user with an `Administrator` role.
      x-badges:
        - color: orange
          label: admin
      tags:
        - users
  '/api/v1/users/{id}/promote':
    parameters:
      - $ref: '#/components/parameters/id'
    patch:
      summary: Promote user as administrator
      operationId: patch-users-id-promote
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagerRead'
              examples:
                Example:
                  value:
                    id: 0
                    name: John
                    email: user@example.com
                    oauth_provider: string
                    preferences:
                      preference_name_1: string
                      preference_name_2: 0
                      preference_name_3: true
                    is_admin: true
                    twofaccounts_count: 0
                    last_seen_at: string
                    created_at: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: |-
        Grants (or denies) administrator permissions to a user.

        `/users` endpoints are restricted to user with an `Administrator` role.
      tags:
        - users
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                is_admin:
                  type: boolean
                  description: The user has administrator rights or not
              required:
                - is_admin
            examples:
              Example:
                value:
                  is_admin: true
        description: ''
      x-badges:
        - color: orange
          label: admin
  '/api/v1/users/{id}/password/reset':
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          example: 1
          minimum: 1
        description: The ID of the resource
    patch:
      summary: Reset user password
      operationId: patch-users-id-password-reset
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagerRead'
              examples:
                Example:
                  value:
                    id: 0
                    name: John
                    email: user@example.com
                    oauth_provider: string
                    preferences:
                      preference_name_1: string
                      preference_name_2: 0
                      preference_name_3: true
                    is_admin: true
                    twofaccounts_count: 0
                    last_seen_at: string
                    created_at: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: |-
        Resets a user password. The user's password will be reset to a new, randomly generated password. The user will then receive an email prompting him to change its password.

        `/users` endpoints are restricted to user with an `Administrator` role.
      tags:
        - users
      x-badges:
        - color: orange
          label: admin
  '/api/v1/users/{id}/pats':
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          example: 1
          minimum: 1
        description: The ID of the resource
    delete:
      summary: Revoke user's personal access tokens
      operationId: delete-users-id-pats
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: |-
        Revokes all personal access tokens of a user. 

        `/users` endpoints are restricted to user with an `Administrator` role.
      tags:
        - users
      x-badges:
        - color: orange
          label: admin
  '/api/v1/users/{id}/authentications':
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          example: 1
          minimum: 1
        description: The ID of the resource
    get:
      summary: Get user's authentications log
      operationId: get-users-id-authentications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationLogCollection'
              examples:
                Example:
                  value:
                    - id: 19
                      ip_address: 127.0.0.1
                      user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/115.0'
                      browser: Firefox
                      platform: Windows
                      device: desktop
                      login_at: 'Thu, May 2, 2024 6:29 AM'
                      logout_at: null
                      login_successful: false
                      duration: null
                      login_method: password
                    - id: 20
                      ip_address: 127.0.0.1
                      user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/115.0'
                      browser: Firefox
                      platform: Windows
                      device: desktop
                      login_at: 'Thu, May 2, 2024 6:32 AM'
                      logout_at: 'Thu, May 2, 2024 6:34 AM'
                      login_successful: true
                      duration: 2 minutes
                      login_method: password
                    - id: 21
                      ip_address: 127.0.0.1
                      user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/115.0'
                      browser: Firefox
                      platform: Windows
                      device: desktop
                      login_at: 'Thu, May 2, 2024 6:39 AM'
                      logout_at: null
                      login_successful: true
                      duration: null
                      login_method: password
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: |-
        Lists user's authentications log records.

        `/users` endpoints are restricted to user with an `Administrator` role.
      tags:
        - users
      parameters:
        - schema:
            type: number
            example: 5
          in: query
          name: limit
          description: Maximum number of log records to return
        - schema:
            type: number
            example: 2
          in: query
          name: period
          description: Length of the time span (in months) over which log records to return have occurred
      x-badges:
        - color: orange
          label: admin
  '/api/v1/users/{id}/credentials':
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          example: 1
          minimum: 1
        description: The ID of the resource
    delete:
      summary: Revoke user's webauthn credentials
      operationId: delete-users-id-credentials
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: |-
        Revokes all webauthn credentials of a user. 

        `/users` endpoints are restricted to user with an `Administrator` role.
      tags:
        - users
      x-badges:
        - color: orange
          label: admin
components:
  schemas:
    2FAccountStore:
      title: Store 2FAccount schema
      type: object
      description: Expected informations to create or preview a 2FA account
      examples:
        - service: MySite
          account: john.doe
          icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          otp_type: totp
          secret: GJTGC5LUNA
          digits: 6
          algorithm: sha1
          period: 30
          counter: null
          group_id: 1
        - service: MySite
          account: john.doe
          icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          otp_type: hotp
          secret: GJTGC5LUNA
          digits: 6
          algorithm: sha1
          period: null
          counter: 0
          group_id: null
        - account: john.doe
          otp_type: totp
      properties:
        service:
          type:
            - string
            - 'null'
          description: The Issuer of the 2FA account
          example: MySite
          pattern: '^[^:]+$'
        account:
          type: string
          description: The Label of the 2FA account
          example: john.doe
          pattern: '^[^:]+$'
        icon:
          type:
            - string
            - 'null'
          example: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          description: The filename of the icon which decorate the 2FA account
        otp_type:
          type: string
          enum:
            - totp
            - hotp
          example: totp
          description: The type of 2FA account
        secret:
          type:
            - string
            - 'null'
          description: A base32 encoded string used by the cryptographic algorithm to generate the One-Time Password.
          example: GJTGC5LUNA
        digits:
          type:
            - integer
            - 'null'
          example: 6
          description: The number of digits of the generated One-Time Password
        algorithm:
          type:
            - string
            - 'null'
          enum:
            - sha1
            - sha256
            - sha512
            - md5
          example: sha1
          description: The algorithm used to generate the One-Time Password
          default: sha1
        period:
          type:
            - integer
            - 'null'
          default: 30
          example: 30
          description: 'For TOTP only: The validity duration of One-Time Password generated for the account'
        counter:
          type:
            - integer
            - 'null'
          example: 15
          description: 'for HOTP only: The value of the counter used to synchronize the account with its verification servers'
          default: 0
        group_id:
          type:
            - integer
            - 'null'
          description: The ID of the group the 2FA account belongs to
          minimum: 0
      required:
        - account
        - otp_type
    2FAccountRead:
      allOf:
        - type: object
          properties:
            id:
              type:
                - integer
                - 'null'
              example: 1
              description: ID of the 2FA account
              minimum: 1
          required:
            - id
        - $ref: '#/components/schemas/2FAccountStore'
    2FAccountUpdate:
      title: Update 2FA Account schema
      type: object
      description: Expected informations to update a 2FA account
      examples:
        - service: MySite
          account: john.doe
          icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          otp_type: totp
          secret: GJTGC5LUNA
          digits: 6
          algorithm: sha1
          period: 30
          group_id: 1
        - service: MySite
          account: john.doe
          icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          otp_type: hotp
          secret: GJTGC5LUNA
          digits: 6
          algorithm: sha1
          counter: 0
          group_id: null
      properties:
        service:
          type:
            - string
            - 'null'
          description: The Issuer of the 2FA account
          example: MySite
          pattern: '^[^:]+$'
        account:
          type: string
          description: The Label of the 2FA account
          example: john.doe
          pattern: '^[^:]+$'
        icon:
          type:
            - string
            - 'null'
          example: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          description: The filename of the icon which decorate the 2FA account
        otp_type:
          type: string
          enum:
            - totp
            - hotp
          example: totp
          description: The type of 2FA account
        secret:
          type: string
          description: A base32 encoded string used by the cryptographic algorithm to generate the One-Time Password
          example: GJTGC5LUNA
        digits:
          type: integer
          example: 6
          description: The number of digits of the generated One-Time Password
        algorithm:
          type: string
          enum:
            - sha1
            - sha256
            - sha512
            - md5
          example: sha1
          description: The algorithm used to generate the One-Time Password
        period:
          type: integer
          example: 30
          description: 'Required for TOTP only: The validity duration of One-Time Password generated for the account'
        counter:
          type: integer
          example: 15
          description: 'Required for HOTP only: The value of the counter used to synchronize the account with its verification servers'
        group_id:
          type:
            - integer
            - 'null'
          description: The ID of the group the 2FA account belongs to
          minimum: 0
      required:
        - service
        - account
        - icon
        - otp_type
        - secret
        - digits
        - algorithm
    2FAccountCollection:
      title: 2FA Accounts Collection schema
      description: An array of 2FA accounts
      examples:
        - - id: 1
            group_id: 1
            service: MySite
            account: john.doe
            icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
            otp_type: totp
            digits: 6
            algorithm: sha1
            secret: GJTGC5LUNA
            period: 30
            counter: null
          - id: 2
            group_id: 1
            service: MyOtherSite
            account: john.doe
            icon: 1pawLLuMx4bOQkrZxM5CIQyFtVq25dtgMkU3rtST.png
            otp_type: hotp
            digits: 8
            algorithm: sha1
            secret: QD5TG6UUJ89F44GV
            period: null
            counter: 15
      type: array
      items:
        $ref: '#/components/schemas/2FAccountRead'
    2FAccountExport:
      allOf:
        - type: object
          properties:
            icon_mime:
              type:
                - string
                - 'null'
              example: image/png
              description: Mime-type of the image
            icon_file:
              type:
                - string
                - 'null'
              example: iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMATSSZLxZNZ7LxhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMKW//A0lifIQSJgQuAAAAAElFTkSuQmCC
              description: 'Content of the image, encoded in base32'
            legacy_uri:
              type:
                - string
              example: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite'
              description: The original otpauth URI of the 2FA account
          required:
            - icon_mime
            - icon_file
            - legacy_uri
        - $ref: '#/components/schemas/2FAccountStore'
      title: Export 2FAccount schema
      description: A single exported 2FA account
      examples:
        - icon_mime: image/png
          icon_file: iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAACXBIWXMATSSZLxZNZ7LxhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMMcYYY4wxxhhjjDHGGGOMKW//A0lifIQSJgQuAAAAAElFTkSuQmCC
          legacy_uri: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite'
          service: MySite
          account: john.doe
          icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          otp_type: totp
          secret: GJTGC5LUNA
          digits: 6
          algorithm: sha1
          period: 30
          counter: null
    2FAccountExportOtpauthURI:
      title: 2FAccountExportOtpauthURI
      x-stoplight:
        id: irovw8l062py0
      type: object
      description: A single 2FA account exported as otpauth URI
      properties:
        uri:
          type: string
          description: The otpauth URI describing the 2FA account
      required:
        - uri
      examples:
        - uri: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite'
    2FAccountMigrated:
      allOf:
        - type: object
          properties:
            id:
              type: integer
              example: 0
              description: ID of the 2FA account
              minimum: -2
              maximum: 0
            group_id:
              type:
                - integer
                - 'null'
              description: The ID of the group the 2FA account belongs to
              minimum: 1
              default: null
          required:
            - id
            - group_id
        - $ref: '#/components/schemas/2FAccountStore'
      description: A single migrated 2FA account
      examples:
        - id: 0
          group_id: null
          service: MySite
          account: john.doe
          icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          otp_type: totp
          secret: GJTGC5LUNA
          digits: 6
          algorithm: sha1
          period: 30
          counter: null
    Otp:
      title: Otp schema
      type: object
      description: One-Time password
      examples:
        - password: '225897'
          otp_type: totp
          generated_at: 1631304659
          period: 30
        - password: '225897'
          otp_type: hotp
          counter: 5
      properties:
        password:
          type: string
          description: the One-Time Password
          minLength: 6
          maxLength: 10
          example: '225897'
        otp_type:
          type: string
          description: The type of the One-Time Password
          enum:
            - totp
            - hotp
          example: totp
        generated_at:
          type: integer
          description: 'TOTP only: The timestamp of the generation time'
          example: 1631304659
        period:
          type: integer
          description: 'TOTP only: The validity period of the password'
          example: 30
        counter:
          type: integer
          description: 'HOTP only: The number of password computing iterations'
          example: 5
      required:
        - password
        - otp_type
    OtpauthUri:
      title: OtpauthUri schema
      type: object
      examples:
        - uri: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite&period=30&algorithm=sha1&digits=6&image=https://www.example.com/image.png'
      properties:
        uri:
          type: string
          example: 'otpauth://totp/MySite:john.doe?secret=GJTGC5LUNA&issuer=MySite&period=30&algorithm=sha1&digits=6&image=https://www.example.com/image.png'
          pattern: '^otpauth:\/\/(totp|hotp)\/.+'
          format: uri
          description: A URI which describe a 2FA account (usually encoded as a QR code) following the otpauth format
      required:
        - uri
      description: An otpauth URI
    GroupRead:
      title: Read Group schema
      type: object
      description: A Group resource
      examples:
        - id: 1
          name: Social networks
          twofaccounts_count: 4
      properties:
        id:
          type: integer
          example: 1
          description: ID of the Group
          minimum: 0
        name:
          type: string
          example: Social networks
          description: Name of the Group
          maxLength: 32
        twofaccounts_count:
          type: integer
          description: Number of 2FA accounts in the group
          minimum: 0
          example: 4
      required:
        - id
        - name
        - twofaccounts_count
    GroupStore:
      title: Store Group schema
      type: object
      properties:
        name:
          type: string
          maxLength: 32
          example: Social networks
          description: The name of the group
      required:
        - name
      examples:
        - name: Social networks
      description: Expected informations to create a group
    GroupCollection:
      title: Group Collection schema
      type: array
      description: An array of Groups
      examples:
        - - id: 0
            name: All
            twofaccounts_count: 9
          - id: 1
            name: Social networks
            twofaccounts_count: 4
      items:
        $ref: '#/components/schemas/GroupRead'
    UserPreference:
      title: User preference schema
      type: object
      examples:
        - key: displayMode
          value: true
          locked: true
      description: A user preference resource
      x-stoplight:
        id: b23a1d8655faa
      properties:
        key:
          type: string
          description: Name of the preference
          example: checkForUpdate
          maxLength: 128
          pattern: '^[a-zA-Z]+'
        value:
          type:
            - string
            - boolean
            - integer
          description: Value of the preference
          example: true
        locked:
          type: boolean
          description: Whether or not the preference is locked by administrator against change
      required:
        - key
        - value
        - locked
    UserPreferenceCollection:
      title: User preference Collection schema
      type: array
      items:
        $ref: '#/components/schemas/UserPreference'
      description: An array of user preferences
      examples:
        - - key: displayMode
            value: grid
          - key: showTokenAsDot
            value: true
          - key: kickUserAfter
            value: 5
      x-stoplight:
        id: 8a5788a19c094
    Setting:
      title: Setting schema
      type: object
      examples:
        - key: checkForUpdate
          value: true
      description: A setting resource
      properties:
        key:
          type: string
          description: Name of the setting
          example: displayMode
          maxLength: 128
          pattern: '^[a-zA-Z]+'
        value:
          type:
            - string
            - boolean
            - integer
          description: Value of the setting
          example: grid
      required:
        - key
        - value
    SettingCollection:
      title: Setting Collection schema
      type: array
      items:
        $ref: '#/components/schemas/Setting'
      description: An array of settings
      examples:
        - - key: useEncryption
            value: false
          - key: checkForUpdate
            value: true
          - key: yourCustomSetting
            value: your custom value
    UserRead:
      title: UserRead
      x-stoplight:
        id: d62wz6a826u78
      type: object
      examples:
        - id: 0
          name: John
          email: user@example.com
          oauth_provider: string
          preferences:
            preference_name_1: string
            preference_name_2: 0
            preference_name_3: true
          is_admin: false
      description: A single user resource
      properties:
        id:
          type: integer
          description: The user Id
        name:
          type: string
          description: The username
          example: John
        email:
          type: string
          format: email
          description: The user email
        oauth_provider:
          type:
            - string
            - 'null'
          description: 'The OAUTH provider for SSO, if relevant'
        preferences:
          description: 'An object which list user preferences values. The number of preferences can vary, as can the name of the preferences.'
          type: object
          properties:
            preference_name_1:
              type: string
              description: A user preference that is a string
            preference_name_2:
              type: integer
              description: A user preference that is a number
            preference_name_3:
              type: boolean
              description: A user preference that is a boolean
        is_admin:
          type: boolean
          default: false
          description: The user has administrator rights or not
      required:
        - id
        - name
        - email
        - oauth_provider
        - preferences
        - is_admin
    UserStore:
      title: Store User schema
      x-stoplight:
        id: b36cpd4jsyjoz
      type: object
      description: Expected informations to register a user
      examples:
        - name: john doe
          email: johndoe@example.com
          password: P4sSw0rD
          password_confirmation: P4sSw0rD
          is_admin: true
      properties:
        name:
          type: string
          description: The name of the user
        email:
          type: string
          description: The email address of the user
        password:
          type: string
          description: The password of the user
        password_confirmation:
          type: string
          description: The password of the user
        is_admin:
          type: boolean
          description: Grant or deny administrator permissions to the user
      required:
        - name
        - email
        - password
        - password_confirmation
        - is_admin
    UserManagerRead:
      allOf:
        - $ref: '#/components/schemas/UserRead'
        - type: object
          properties:
            twofaccounts_count:
              type: integer
              description: Number of 2FA accounts registered
            last_seen_at:
              type: string
              description: Last time the user was seen
            created_at:
              type: string
              description: Time of user registration
          required:
            - twofaccounts_count
            - last_seen_at
            - created_at
      examples:
        - id: 0
          name: John
          email: user@example.com
          oauth_provider: string
          preferences:
            preference_name_1: string
            preference_name_2: 0
            preference_name_3: true
          is_admin: false
          twofaccounts_count: 10
          last_seen_at: 1 weeks ago
          created_at: 3 weeks ago
    UserManagerCollection:
      title: UserManagerCollection
      x-stoplight:
        id: 01f2nm1ra2hqf
      type: array
      description: An array of managed users
      items:
        $ref: '#/components/schemas/UserManagerRead'
    AuthenticationLog:
      type: object
      x-examples:
        Example 1:
          id: 20
          ip_address: 127.0.0.1
          user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/115.0'
          browser: Firefox
          platform: Windows
          device: desktop
          login_at: 'Thu, May 2, 2024 6:32 AM'
          logout_at: 'Thu, May 2, 2024 6:32 AM'
          login_successful: true
          duration: 8 seconds
          login_method: password
      examples:
        - id: 20
          ip_address: 127.0.0.1
          user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/115.0'
          browser: Firefox
          platform: Windows
          device: desktop
          login_at: 'Thu, May 2, 2024 6:32 AM'
          logout_at: 'Thu, May 2, 2024 6:32 AM'
          login_successful: true
          duration: 8 seconds
          login_method: password
      properties:
        id:
          type: integer
          description: The authentication Id
        ip_address:
          type: string
          description: IP Address that performed the authentication
        user_agent:
          type: string
          description: User agent of the browser that performed the authentication
        browser:
          type: string
          description: Browser that performed the authentication
        platform:
          type: string
          description: Platform of the browser that performed the authentication
        device:
          type: string
          description: Device that performed the authentication
        login_at:
          type:
            - string
            - 'null'
          description: Date and time of the login
        logout_at:
          type:
            - string
            - 'null'
          description: Date and time of the logout
        login_successful:
          type: boolean
          description: Whether the login was successful or not
        duration:
          type:
            - string
            - 'null'
          description: Elapsed time between login and logout
        login_method:
          type: string
          description: Method used to login
      description: A single authentications log record
    AuthenticationLogCollection:
      title: AuthenticationLogCollection
      x-stoplight:
        id: og9vhx68csubr
      type: array
      items:
        $ref: '#/components/schemas/AuthenticationLog'
      description: An array of authentication log records
      examples:
        - - id: 20
            ip_address: 127.0.0.1
            user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/115.0'
            browser: Firefox
            platform: Windows
            device: desktop
            login_at: 'Thu, May 2, 2024 6:32 AM'
            logout_at: 'Thu, May 2, 2024 6:32 AM'
            login_successful: true
            duration: 8 seconds
            login_method: password
  parameters:
    id:
      name: id
      in: path
      required: true
      schema:
        type: integer
        example: 1
        minimum: 1
      description: The ID of the resource
    withSecret:
      name: withSecret
      in: query
      required: false
      schema:
        type: boolean
      description: Set to true (or 1) to append the Secret property to the returned 2FA account
    ids:
      name: ids
      in: query
      required: true
      schema:
        type: string
        pattern: '^\d+(,{1}\d+)*$'
        example: '1,5,18'
      description: A comma-separated list of IDs. A maximum of 100 IDs may be provided
    name:
      name: name
      in: path
      required: true
      schema:
        type: string
        pattern: '^[a-zA-Z]+'
        maxLength: 128
        example: displayMode
      description: Name of the resource
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            description: ''
            properties:
              message:
                type: string
                description: An information message
                example: Model not found
            required:
              - message
          examples:
            Example:
              value:
                message: Model not found
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: An information message
                example: Unauthenticated
            required:
              - message
          examples:
            Example:
              value:
                message: Unauthenticated
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: An information message
                example: Conflict
            required:
              - message
          examples:
            Example:
              value:
                message: Conflict
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: An information message
                example: Forbidden
            required:
              - message
          examples:
            Example:
              value:
                message: Forbidden
    ValidationError:
      description: Validation errors
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: An information message
                example: The given data was invalid
              errors:
                description: A collection of fields with their respective errors
                type: object
                properties:
                  fieldName:
                    type: array
                    description: A field with errors
                    items:
                      type: string
                      example: The field2 must be a number
            required:
              - message
              - errors
          examples:
            Example:
              value:
                message: The given data was invalid.
                errors:
                  field1:
                    - The field1 is required.
                    - The field1 must be a string.
                  field2:
                    - The field2 must be a number.
    OK:
      description: OK
      content:
        application/json:
          schema:
            description: ''
            type: object
            x-examples:
              example-1:
                message: success
            properties:
              message:
                type: string
                description: An information message
                example: success
            required:
              - message
          examples:
            Example:
              value:
                message: success
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            description: ''
            type: object
            x-examples:
              example-1:
                message: success
            properties:
              message:
                type: string
                description: An information message
                example: bad request
              reason:
                type: object
                description: The reasons why the error occured
                properties:
                  param1:
                    type: string
                    description: A reason
                    example: This request accept only one parameter
            required:
              - message
          examples:
            Example:
              value:
                message: bad request
                reason:
                  param1: This request accept only one parameter
    ServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: An information message
                example: Something failed on server side
            required:
              - message
          examples:
            Example:
              value:
                message: Something failed on server side
  securitySchemes:
    Bearer-Auth:
      type: http
      scheme: bearer
      description: Provide your bearer token in the Authorization header when making requests to protected resources. See the 'Settings > OAuth' section of your 2FAuth instance to generate personal access tokens.
  requestBodies: {}
tags:
  - name: groups
  - name: icons
  - name: one-time password
  - name: qrcode
  - name: settings
  - name: twofaccounts
  - name: user
  - name: user preference
  - name: users
security:
  - Bearer-Auth: []