SignalWire Multi-Factor Authentication API

openapi: 3.2.0
info:
  title: SignalWire REST Multi-Factor Authentication API
  version: 1.0.0
  contact:
    name: SignalWire
    url: https://support.signalwire.com/portal/en/newticket?departmentId=1029313000000006907&layoutId=1029313000000074011
    email: support@signalwire.com
  license:
    name: MIT
    url: https://github.com/signalwire/docs/blob/main/LICENSE
  termsOfService: https://signalwire.com/legal/signalwire-cloud-agreement
  description: Multi-factor authentication adds security to your application by requesting a user to be verified via voice or via text message. It can also be used for One Time Password flows (OTP).
servers:
- url: https://{space_name}.signalwire.com
  description: SignalWire API
  variables:
    space_name:
      default: '{Your_Space_Name}'
      description: Your SignalWire Space name
security:
- SignalWireBasicAuth: []
tags:
- name: Multi-Factor Authentication
  description: Multi-factor authentication adds security to your application by requesting a user to be verified via voice or via text message. It can also be used for One Time Password flows (OTP).
  externalDocs:
    url: https://signalwire.com/docs/apis
    description: Developer documentation on SignalWire REST APIs
paths:
  /api/relay/rest/mfa/call:
    post:
      operationId: request_mfa_call
      summary: Request MFA token via call
      description: 'Sends a multi-factor authentication code via voice call.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Management_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '422':
          description: The request failed validation. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.ValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Multi-Factor Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaRequest'
  /api/relay/rest/mfa/sms:
    post:
      operationId: request_mfa_sms
      summary: Request MFA token via SMS
      description: 'Sends a multi-factor authentication code via SMS.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Management_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '422':
          description: The request failed validation. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.ValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Multi-Factor Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaRequest'
  /api/relay/rest/mfa/{mfa_request_id}/verify:
    post:
      operationId: verify_mfa_token
      summary: Verify MFA token
      description: 'Verifies a multi-factor authentication code.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Management_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).'
      parameters:
      - $ref: '#/components/parameters/MfaRequestIdPath'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaVerifyResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '422':
          description: The request failed validation. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.ValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Multi-Factor Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaVerifyRequest'
components:
  schemas:
    MfaVerifyRequest:
      type: object
      required:
      - token
      properties:
        token:
          type: string
          description: The token to verify.
          examples:
          - '123456'
      unevaluatedProperties:
        not: {}
      description: MFA verification request model.
    Types.StatusCodes.StatusCode401:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Unauthorized
      unevaluatedProperties:
        not: {}
      description: Access is unauthorized.
    MfaResponse:
      type: object
      required:
      - id
      - success
      - to
      - channel
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/uuid'
          description: The MFA request ID. Save this for verification.
          examples:
          - 3fa85f64-5717-4562-b3fc-2c963f66afa6
        success:
          type: boolean
          description: Whether the request was successfully queued.
          examples:
          - true
        to:
          type: string
          description: The destination of the MFA request.
          examples:
          - '+15554422333'
        channel:
          type: string
          description: Can be sms for a text message or call for a phone call.
          examples:
          - call
      unevaluatedProperties:
        not: {}
      description: MFA response model.
    MfaRequest:
      type: object
      required:
      - to
      properties:
        to:
          type: string
          description: The E164 number to use as the destination.
          examples:
          - '+14043287382'
        from:
          type: string
          description: The E164 number from your account to use as the origin of the message. SignalWire will use a special verified number if not specified.
          examples:
          - '+12029167968'
        message:
          type: string
          description: Specify a custom message to send before the token. The message must fit within one segment; either 160 characters or 70 characters when using non-GSM symbols.
          examples:
          - Here is your code
          default: 'Your Personal Authorization Code is:'
        token_length:
          type: integer
          format: int32
          description: The number of characters in the token, from 4 to 20. Defaults to 6.
          examples:
          - 6
          default: 6
        valid_for:
          type: integer
          format: int32
          description: The number of seconds the token is considered valid for. Defaults to 3600, with a maximum of 604800.
          examples:
          - 3600
          default: 3600
        max_attempts:
          type: integer
          format: int32
          description: The number of allowed verification attempts, including the first one, from 1 to 20. Defaults to 3.
          examples:
          - 3
          default: 3
        allow_alphas:
          type: boolean
          description: Set to true or false, whether to include letters or just numbers in the token. Defaults to false (numbers only).
          examples:
          - false
          default: false
      unevaluatedProperties:
        not: {}
      description: MFA request model.
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
    Types.StatusCodes.ValidationError:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Types.StatusCodes.SpaceApiErrorItem'
          description: List of validation errors.
      unevaluatedProperties:
        not: {}
      description: The request failed validation. See errors for details.
    Types.StatusCodes.SpaceApiErrorItem:
      type: object
      required:
      - detail
      - status
      - title
      - code
      properties:
        detail:
          type: string
          description: A description of what caused the error.
          examples:
          - Label can't be blank
        status:
          type: string
          description: The HTTP status code.
          examples:
          - '422'
        title:
          type: string
          description: A short summary of the error type.
          examples:
          - Invalid Attribute
        code:
          type: string
          description: The error code.
          examples:
          - '422'
      unevaluatedProperties:
        not: {}
      description: Details about a specific validation error.
    MfaVerifyResponse:
      type: object
      required:
      - success
      properties:
        success:
          type: boolean
          description: Whether the token was successfully verified by the API. When `max_attempts` are reached or the request is no longer valid, the endpoint will return a `404 Not Found`.
          examples:
          - true
      unevaluatedProperties:
        not: {}
      description: MFA verification response model.
    Types.StatusCodes.StatusCode500:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          enum:
          - Internal Server Error
      unevaluatedProperties:
        not: {}
      description: An internal server error occurred.
  parameters:
    MfaRequestIdPath:
      name: mfa_request_id
      in: path
      required: true
      description: The MFA request ID.
      schema:
        $ref: '#/components/schemas/uuid'
  securitySchemes:
    SignalWireBasicAuth:
      type: http
      scheme: Basic
      description: 'SignalWire Basic Authentication using Project ID and API Token.


        The client sends HTTP requests with the Authorization header containing

        the word Basic followed by a space and a base64-encoded string of project_id:token.

        The project ID will be used as the username and the API token as the password.


        Example:

        ```

        Authorization: Basic base64(project_id:token)

        ```'
      x-fern-basic:
        username:
          name: project_id
          env: SIGNALWIRE_PROJECT_ID
        password:
          name: api_token
          env: SIGNALWIRE_API_TOKEN
    SignalWireBearerAuth:
      type: http
      scheme: Bearer
      description: 'SignalWire Bearer Token Authentication for subscriber endpoints.

        The client sends HTTP requests with the Authorization header containing

        the word Bearer followed by a space and the subscriber token.


        Example:

        ```

        Authorization: Bearer <subscriber_token>

        ```'