2fauth-api-latest.yaml

openapi: 3.1.0
info:
  title: 2FAuth API
  version: 1.10.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'
                        next_password: '255745'
                        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
                Example with account shared with me:
                  value:
                    - id: 25
                      group_id: 8
                      service: AnotherSite
                      account: jane.doe
                      icon: p0TmC8xswemEgQe3YRT8g0ohBxT7hHpvp0TmC8xswe.png
                      otp_type: totp
                      digits: 6
                      algorithm: sha1
                      period: 30
                      counter: null
                      is_borrowed: true
                      shared_by: Jane
                    - 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 account I share:
                  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
                      is_shared: true
                      is_shared_with_all: true
                    - 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'
      operationId: get-twofaccounts
      description: |-
        Find all 2FA accounts.

        The returned accounts can be either those owned by the authenticated user or accounts shared with him (when sharing is enabled).

        Specific properties are presents in the response payload depending on the context (see available examples bellow):

        - The `secret` property is present when `withSecret` query param is set to `true`.
        - The `otp` array is present when `withOtp` query param is set to `true`.
        - The `is_borrowed` and `shared_by` properties are presents when the account is shared with the authenticated user (the Sharing feature must be globally enabled).
        - The `is_shared` and `is_shared_with_all` properties are presents when the account is shared by the authenticated user (the Sharing feature must be globally enabled).
      parameters:
        - $ref: '#/components/parameters/withSecret'
        - schema:
            type: string
            example: '1,20,9,456'
          in: query
          name: ids
          description: Comma-separated list of IDs used to filter 2FA accounts returned in the response
        - $ref: '#/components/parameters/withOtp'
    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
                Example for account shared with me:
                  value:
                    id: 1
                    service: MySite
                    account: jane.doe
                    icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                    otp_type: totp
                    secret: VHIGC5PLKM
                    digits: 6
                    algorithm: sha1
                    period: 30
                    counter: null
                    group_id: 5
                    is_borrowed: true
                    shared_by: Jane
                Example for account shared by me:
                  value:
                    id: 1
                    service: MySite
                    account: john.doe
                    icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
                    otp_type: totp
                    secret: GJTGC5LUNA
                    digits: 6
                    algorithm: sha1
                    period: 30
                    counter: null
                    group_id: 1
                    is_shared: true
                    is_shared_with_all: true
        '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.

        The returned account can be an account owned by the authenticated user or an account shared with him (when Sharing is enabled).

        Specific properties are presents in the response payload depending on the context (see available examples bellow):

        - The `secret` property is present when `withSecret` query param is set to `true`.
        - The `otp` array is present when `withOtp` query param is set to `true`.
        - The `is_borrowed` and `shared_by` properties are presents when the account is shared with the authenticated user (the Sharing feature must be globally enabled).
        - The `is_shared` and `is_shared_with_all` properties are presents when the account is shared by the authenticated user (the Sharing feature must be globally enabled).
      parameters:
        - $ref: '#/components/parameters/withSecret'
        - $ref: '#/components/parameters/withOtp'
    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}/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 matching the specified ID.

        The account can be an account owned by the authenticated user or an account shared with him (when Sharing is enabled).
  '/api/v1/twofaccounts/{id}/owner':
    patch:
      summary: Transfer ownership
      operationId: patch-twofaccounts-id-owner
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  twofaccount_id:
                    type: integer
                    x-stoplight:
                      id: 2ryavv4mib7o8
                    minimum: 1
                    description: ID of the patched 2FA account
                  owner_id:
                    type: integer
                    x-stoplight:
                      id: 0kndoov4k1f1q
                    minimum: 1
                    description: User ID of the new owner
                required:
                  - twofaccount_id
                  - owner_id
              examples:
                Example:
                  value:
                    twofaccount_id: 1
                    owner_id: 1
        '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'
      description: |-
        Transfers the ownership of a 2FA account to another user of the 2FAuth instance.

        > #### Important
        > This endpoint can only be used if the app setting `enableSharing` is enabled. It will return a `403 Forbidden` response otherwise.
      parameters: []
      tags:
        - twofaccounts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                new_owner_id:
                  type: integer
                  x-stoplight:
                    id: ic99lni10sedl
                  minimum: 1
                  description: ID of the new owner
                  example: 5
                confirm_password:
                  type: string
                  x-stoplight:
                    id: bgbmfb55n5udm
                  description: Password of the authenticated user that make the request
                  example: P4s$w0rD
              required:
                - new_owner_id
                - confirm_password
            examples:
              Example:
                value:
                  new_owner_id: 5
                  confirm_password: P4s$w0rD
        description: ''
    parameters:
      - $ref: '#/components/parameters/id'
  '/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,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'
                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}/recipients':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Get users with whom to share a 2FA account
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/2FAccountShareRecipient'
                  x-stoplight:
                    id: 95aw8enerpwau
              examples:
                Example:
                  value:
                    - id: 1
                      name: John DOE
                      is_shared_with: true
                      is_shared_since: 'Thu, May 2, 2024 6:32 AM'
                    - id: 1
                      name: Jane DOE
                      is_shared_with: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-twofaccounts-id-recipients
      description: |-
        Find users who can be set as recipients for a new 2FA account sharing.

        This endpoint only returns something if:
        - the user email address matches the query parameter value exactly
        - the username matches the query parameter value partially.
      parameters:
        - schema:
            type: string
            example: '?filter[name]=do'
          in: query
          name: 'filter[nameOrEmail]'
          description: String used to retrieve user by name or by email
          required: true
      tags:
        - twofaccounts
        - sharing
  '/api/v1/twofaccounts/{id}/shares':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Get sharing details
      tags:
        - twofaccounts
        - sharing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountShares'
              examples:
                Example for account shared with all users:
                  value:
                    twofaccount_id: 1
                    is_shared_with_all: true
                Example for account shared with specific users:
                  value:
                    twofaccount_id: 1
                    is_shared_with_all: false
                    specific_users:
                      - id: 2
                        name: John DOE
                        is_shared_with: true
                        is_shared_since: 'Thu, May 2, 2025 6:32 AM'
                      - id: 3
                        name: Jane DOE
                        is_shared_with: true
                        is_shared_since: 'Thu, May 3, 2026 3:54 AM'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: get-twofaccounts-id-shares
      description: Find all sharings for a 2FA account owned by the authenticated user.
    post:
      summary: Share a 2FA account
      operationId: post-twofaccounts-id-shares
      responses:
        '200':
          description: Received when the 2FA account was already shared with each provided user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountShares'
              examples:
                Example:
                  value:
                    twofaccount_id: 1
                    is_shared_with_all: false
                    specific_users:
                      - id: 2
                        name: John DOE
                        is_shared_with: true
                        is_shared_since: 'Thu, May 2, 2025 6:32 AM'
                      - id: 3
                        name: Jane DOE
                        is_shared_with: true
                        is_shared_since: 'Thu, May 3, 2026 3:54 AM'
        '201':
          description: Received when the 2FA account was not already shared with at least one of the provided users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountShares'
              examples:
                Example:
                  value:
                    twofaccount_id: 1
                    is_shared_with_all: false
                    specific_users:
                      - id: 2
                        name: John DOE
                        is_shared_with: true
                        is_shared_since: 'Thu, May 2, 2025 6:32 AM'
                      - id: 3
                        name: Jane DOE
                        is_shared_with: true
                        is_shared_since: 'Thu, May 3, 2026 3:54 AM'
        '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'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_ids:
                  x-stoplight:
                    id: u9iipzmarg1lm
                  type: array
                  description: List of user IDs with whom the 2FA account must be shared
                  minItems: 1
                  items:
                    x-stoplight:
                      id: l4q842uaszaxv
                    type: integer
              required:
                - user_ids
            examples:
              Example:
                value:
                  user_ids:
                    - 2
                    - 3
        description: ''
      description: |-
        Shares a 2FA account owned by the authenticated user with specific users of the 2FAuth instance. This endpoint creates new shares for given users with whom the 2FA account is not already shared.

        > The user list provided in the request body is not the comprehensive list of users with whom the 2FA account must be shared.

        You can't share an account with specific users if the account has already been shared with all users. You will receive a `409 Conflict` response.
      tags:
        - twofaccounts
        - sharing
    delete:
      summary: Stop sharing a 2FA account
      operationId: delete-twofaccounts-id-shares
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      description: 'Revokes any sharing of a 2FA account owned by the authenticated user, whether it''s shared with all users (`All users` scope) or specific users.'
      tags:
        - twofaccounts
        - sharing
  '/api/v1/twofaccounts/{id}/shares/all':
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      summary: Share a 2FA account with all users
      operationId: post-twofaccounts-id-shares-all
      responses:
        '200':
          description: Received when the 2FA account was already shared with all user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountShares'
              examples:
                Example:
                  value:
                    twofaccount_id: 1
                    is_shared_with_all: true
        '201':
          description: Received when the 2FA account was not already shared with all users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/2FAccountShares'
              examples:
                Example:
                  value:
                    twofaccount_id: 1
                    is_shared_with_all: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      requestBody:
        content: {}
        description: ''
      description: |-
        Shares a 2FA account owned by the authenticated user with all current and future users of the 2FAuth instance, aka the `All users` scope.

        Any specific user shares will be canceled.
      tags:
        - twofaccounts
        - sharing
  '/api/v1/twofaccounts/{id}/shares/{userid}':
    parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/userid'
    delete:
      summary: Stop sharing a 2FA account with a specific user
      operationId: delete-twofaccounts-id-shares-userid
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      description: |-
        Revokes a specific user share of a 2FA account owned by the authenticated user.

        You can't stop sharing an account with specific user if the account is currently shared with all users (`All users` scope). You will receive a `409 Conflict` response.
      tags:
        - twofaccounts
        - sharing
  /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/OrderedIds'
        '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/features:
    get:
      summary: Get all 2FAuth features
      tags:
        - feature
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feature'
                  x-stoplight:
                    id: ynvqrgnso5bff
              examples:
                Example:
                  value:
                    - name: sharing
                      state: enabled
                    - name: iconPack
                      state: enabled
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: get-features
      description: |-
        Lists specific application features that may be available on the 2FAuth instance.

        The main purpose is to determine the capabilities of the running 2FAuth server in order to adapt the behavior of its clients (web app, web extension, mobile app, etc.).
  /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/groups/reorder:
    post:
      summary: Save order of the groups collection
      operationId: post-groups-reorder
      responses:
        '200':
          $ref: '#/components/responses/OrderedIds'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
      description: Saves the order of the authenticated user's groups. This allows to always serve the groups collection sorted in a user defined order.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                orderedIds:
                  type: array
                  uniqueItems: true
                  description: An array of group IDs ordered in the wished order
                  items:
                    type: integer
              required:
                - orderedIds
            examples:
              Example:
                value:
                  orderedIds:
                    - 3
                    - 1
                    - 4
                    - 2
        description: ''
      tags:
        - groups
    parameters: []
  /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/default:
    post:
      summary: Query an official icon
      tags:
        - icons
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  example-1:
                    filename: wspRWRSCo62kY76JFquzqq8Y2jJO1iEowZ3JsMCw.png
                properties:
                  filename:
                    type: string
                    example: wspRWRSCo62kY76JFquzqq8Y2jJO1iEowZ3JsMCw.png
                    description: The name of the icon file stored on the server
                required:
                  - filename
              examples:
                Example:
                  value:
                    filename: wspRWRSCo62kY76JFquzqq8Y2jJO1iEowZ3JsMCw.png
        '204':
          description: No Content (returned when the requested icon does not exist on the external source)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      operationId: post-official-icons
      description: |-
        Use this endpoint to get the official icon of a given "service": A website, an app, a brand.

        When this endpoint is requested, 2FAuth makes a single request to an external icons collection to get the icon of the posted service. If the icon is available, 2FAuth fetches and stores the file in its public icons directory `/storage/icons/`.
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - description: Request body for fetching an icon collection
                  properties:
                    service:
                      type: string
                      description: The name of the service whose icon we want to fetch
                    iconCollection:
                      type:
                        - string
                        - 'null'
                      description: 'The name of the icon collection to query. If omitted, defaults to the icon collection defined in the user preferences.'
                      enum:
                        - tfa
                        - selfh
                        - dashboardicons
                    variant:
                      type: string
                      x-stoplight:
                        id: ardbd0lzneksn
                      description: The icon flavor to fetch at first
                      enum:
                        - regular
                        - light
                        - dark
                  required:
                    - service
                - x-stoplight:
                    id: umc06x5az0xj4
                  description: Request body for fetching an icon pack
                  properties:
                    service:
                      type: string
                      x-stoplight:
                        id: 99jr6c5hw5fjm
                      description: The name of the service whose icon we want to fetch
                    iconPack:
                      type: string
                      x-stoplight:
                        id: vdtcs1bv4nqmk
                      description: 'The name of the icon pack to query. If omitted, defaults to the icon pack defined in the user preferences.'
                  required:
                    - service
              type: object
            examples:
              Example for selfh.st:
                value:
                  service: 1password
                  iconCollection: selfh
                  variant: light
              Example for dashboardicons.com:
                value:
                  service: 1password
                  iconCollection: dashboardicons
                  variant: dark
              Example for an icon pack:
                value:
                  service: 1password
                  iconPack: myIconPack
        description: ''
    parameters: []
  /api/v1/icons/packs:
    parameters: []
    get:
      summary: Get all icon packs
      operationId: get-icons-packs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: Array of available icon packs
                items:
                  x-stoplight:
                    id: nfoo6bbosr3if
                  type: object
                  properties:
                    name:
                      type: string
                      x-stoplight:
                        id: 0wyofcpe38myv
                      description: name of the icon pack
                  required:
                    - name
              examples:
                Example:
                  value:
                    - name: icon_pack
                    - name: other_icon_pack
      description: Find all available icon packs hosted on the server that can be used to set the `iconPack` user preference
      tags:
        - icons
  '/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
      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'
        - type: object
          x-stoplight:
            id: sx1ttjsrwfhr9
          properties:
            is_borrowed:
              type: boolean
              x-stoplight:
                id: y3a14e50hotzl
              description: Indicates if the account is shared with you by another user
            shared_by:
              type: string
              x-stoplight:
                id: t7fqjm0mi44h0
              description: Name of the user who share the account with you
            is_shared:
              type: boolean
              x-stoplight:
                id: hikxw95fgnhjt
              description: Indicates if the account is shared by you
            is_shared_with_all:
              type: boolean
              x-stoplight:
                id: 3i03x81dlmt85
              description: Indicates if you share this account with all users
            otp:
              type: array
              x-stoplight:
                id: gezoshwpr7rhp
              items:
                $ref: '#/components/schemas/Otp'
                x-stoplight:
                  id: ufvekrixybk2u
      examples:
        - id: 1
          service: MySite
          account: john.doe
          icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          otp_type: totp
          secret: GJTGC5LUNA
          digits: 6
          algorithm: sha1
          period: 30
          counter: null
          group_id: 1
          is_borrowed: true
          shared_by: Jane
        - id: 1
          service: MySite
          account: john.doe
          icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          otp_type: totp
          secret: GJTGC5LUNA
          digits: 6
          algorithm: sha1
          period: 30
          counter: null
          group_id: 1
          is_shared: true
          is_shared_with_all: true
        - id: 1
          service: MySite
          account: john.doe
          icon: ZMlzmrPsrWSWVt4fZouFVrt2w38D0PnXiyZQvDcY.png
          otp_type: totp
          secret: GJTGC5LUNA
          digits: 6
          algorithm: sha1
          period: 30
          counter: null
          group_id: 1
          otp:
            - password: '225897'
              next_password: '958857'
              otp_type: totp
              generated_at: 1631304659
              period: 30
    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
    2FAccountShares:
      title: 2FAccountShares
      x-stoplight:
        id: jhd6h9gfroi04
      description: Sharing informations for a given 2FA account
      examples:
        - twofaccount_id: 1
          is_shared_with_all: true
        - twofaccount_id: 1
          is_shared_with_all: false
          specific_users:
            - id: 2
              name: John DOE
              is_shared_with: true
              is_shared_since: 'Thu, May 2, 2025 6:32 AM'
            - id: 3
              name: Jane DOE
              is_shared_with: true
              is_shared_since: 'Thu, May 3, 2026 3:54 AM'
      type: object
      properties:
        twofaccount_id:
          type: integer
          x-stoplight:
            id: 51lmii6lp485m
          minimum: 1
          description: ID of the shared 2FA account
        is_shared_with_all:
          type: boolean
          x-stoplight:
            id: tl3nbjl19jf83
          description: Indicates if the 2FA account is shared using the `All users` scope
        specific_users:
          type: array
          x-stoplight:
            id: sdwkttculjn5o
          description: |-
            **Present only if the account is shared with specific users**  
            The list of users with whom the 2FA account has been shared explicitly
          items:
            $ref: '#/components/schemas/2FAccountShareRecipient'
            x-stoplight:
              id: il8nno7b8s5qb
      required:
        - twofaccount_id
        - is_shared_with_all
    2FAccountShareRecipient:
      title: 2FAccountShareRecipient
      x-stoplight:
        id: bwcujrhom9885
      type: object
      description: A single sharing recipient
      examples:
        - id: 1
          name: John
          is_shared_with: true
          is_shared_since: 'Thu, May 2, 2024 6:32 AM'
      properties:
        id:
          type: integer
          x-stoplight:
            id: ov8vmf0dlzbwk
          description: ID of the user
          minimum: 1
        name:
          type: string
          x-stoplight:
            id: ajih3fv5q9q62
          description: Name of the user
        is_shared_with:
          type: boolean
          x-stoplight:
            id: qsv10fr8458pm
          description: Indicates if the 2FA account is shared with this user
        is_shared_since:
          type: string
          x-stoplight:
            id: kd2pcs27147an
          description: Date the 2FA account was shared with this user
      required:
        - id
        - name
        - is_shared_with
    Otp:
      title: Otp schema
      type: object
      description: One-Time password
      examples:
        - password: '225897'
          next_password: '958857'
          otp_type: totp
          generated_at: 1631304659
          period: 30
        - password: '225897'
          otp_type: hotp
          counter: 5
      properties:
        password:
          type: string
          description: The current One-Time Password
          minLength: 6
          maxLength: 10
          example: '225897'
        next_password:
          type: string
          x-stoplight:
            id: xr5f78tepa6p2
          description: 'For TOTP Only: The next One-Time Password'
          minLength: 6
          maxLength: 10
        otp_type:
          type: string
          description: The type of the One-Time Password
          enum:
            - totp
            - hotp
          example: totp
        generated_at:
          type: integer
          description: 'For TOTP only: The timestamp of the generation time'
          example: 1631304659
        period:
          type: integer
          description: 'For TOTP only: The validity period of the password'
          example: 30
        counter:
          type: integer
          description: 'For 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
    Feature:
      title: Feature
      x-stoplight:
        id: vc1izk6m37dxb
      type: object
      description: An app feature resource
      examples:
        - name: sharing
          state: enabled
      properties:
        name:
          type: string
          x-stoplight:
            id: 9861phusmzlwd
          description: Name of the feature
          enum:
            - iconPack
            - sharing
            - showNextOtp
        state:
          type: string
          x-stoplight:
            id: 9mzbk7ofdckef
          enum:
            - enabled
            - disabled
          description: Availability of the feature
      required:
        - name
        - state
  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 2FA account returned in the response. Has no effect when requested 2FA account is not owned.
    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
    userid:
      name: userid
      in: path
      required: true
      schema:
        type: integer
        example: 1
        minimum: 1
      description: The ID of a user resource
    withOtp:
      name: withOtp
      in: query
      required: false
      schema:
        type: boolean
      description: Set to true (or 1) to append an OTP object to 2FA account of type `TOTP` returned in the response.
  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
    OrderedIds:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                x-stoplight:
                  id: 8q85m006zd5vz
                description: An information message
              orderedIds:
                type: array
                x-stoplight:
                  id: i6vuanfnnlvfp
                description: Ordered list of IDs as saved
                items:
                  x-stoplight:
                    id: mmp17iz1jdl47
                  type: integer
            required:
              - message
              - orderedIds
          examples:
            Example:
              value:
                message: order saved
                orderedIds:
                  - 0
                  - 5
                  - 3
                  - 2
                  - 4
                  - 1
  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: feature
  - name: groups
  - name: icons
  - name: one-time password
  - name: qrcode
  - name: settings
  - name: sharing
  - name: twofaccounts
  - name: user
  - name: user preference
  - name: users
security:
  - Bearer-Auth: []