Mail-in-a-Box MFA API

openapi: 3.2.0
info:
  title: Mail-in-a-Box MFA API
  description: 'Mail-in-a-Box API HTTP specification.


    # Introduction

    This API is documented in **OpenAPI format**.

    (View the full HTTP specification.)


    All endpoints are relative to `https://{host}/admin` and are secured with `Basic Access` authentication. If you have multi-factor authentication enabled, authentication with a `user:password` combination will fail unless a valid OTP is supplied via the `x-auth-token` header. Authentication via a `user:user_key` pair is possible without the header being present.'
  contact:
    name: Mail-in-a-Box support
    url: https://mailinabox.email/
  license:
    name: CC0 1.0 Universal
    url: https://creativecommons.org/publicdomain/zero/1.0/legalcode
  version: 0.51.0
  x-logo:
    url: https://mailinabox.email/static/logo.png
    altText: Mail-in-a-Box logo
servers:
- url: https://{host}/admin
  variables:
    host:
      default: box.example.com
      description: The API hostname.
security:
- basicAuth: []
tags:
- name: MFA
  description: Manage multi-factor authentication schemes. Currently, only TOTP is supported.
paths:
  /mfa/status:
    post:
      tags:
      - MFA
      summary: Retrieve MFA status for you or another user
      description: Retrieves which type of MFA is used and configuration
      operationId: mfaStatus
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://{host}/admin/mfa/status\" \\\n  -u \"<email>:<password>\"\n"
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaStatusResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mfa/totp/enable:
    post:
      tags:
      - MFA
      summary: Enable TOTP authentication
      description: Enables TOTP authentication for the currently logged-in admin user
      operationId: mfaTotpEnable
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://{host}/admin/mfa/totp/enable\" \\\n  -d \"code=123456\" \\\n  -d \"secret=<string>\" \\\n  -u \"<email>:<password>\"\n"
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MfaEnableRequest'
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MfaEnableSuccessResponse'
        400:
          description: Bad request
          content:
            text/html:
              schema:
                type: string
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
  /mfa/disable:
    post:
      tags:
      - MFA
      summary: Disable multi-factor authentication for you or another user
      description: Disables multi-factor authentication for the currently logged-in admin user or another user if a 'user' parameter is submitted. Either disables all multi-factor authentication methods or the method corresponding to the optional property `mfa_id`.
      operationId: mfaTotpDisable
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MfaDisableRequest'
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://{host}/admin/mfa/totp/disable\" \\\n  -u \"<email>:<user_key>\"\n"
      responses:
        200:
          description: Successful operation
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/MfaDisableSuccessResponse'
        403:
          description: Forbidden
          content:
            text/html:
              schema:
                type: string
components:
  schemas:
    MfaDisableRequest:
      type: object
      properties:
        mfa_id:
          type:
          - string
          - 'null'
    MfaStatusResponse:
      type: object
      properties:
        enabled_mfa:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
            type:
              type: string
            label:
              type: string
        new_mfa:
          type: object
          properties:
            type:
              type: string
            secret:
              type: string
            qr_code_base64:
              type: string
    MfaEnableSuccessResponse:
      type: string
    MfaDisableSuccessResponse:
      type: string
    MfaEnableRequest:
      type: object
      required:
      - secret
      - code
      properties:
        secret:
          type: string
        code:
          type: string
        label:
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Credentials can be supplied using the `Authorization` header in

        format `Authorization: Basic {access-token}`.


        The `access-token` is comprised of the Base64 encoding of `username:password`.

        The `username` is the mail user''s email address, and `password` can either be the mail user''s

        password, or the `api_key` returned from the `login` operation.


        When using `curl`, you can supply user credentials using the `-u` or `--user` parameter.

        '
externalDocs:
  description: Find out more about Mail-in-a-box.
  url: https://mailinabox.email/