{"openapi":"3.0.0","info":{"title":"2FA API","description":"Send One Time Passwords (OTPs) using SMS or text-to-speech (TTS). Add a second layer of security to your applications with the 2FA API. The flexibility of multiple delivery methods ensures your users get their OTP.","version":"1.0"},"servers":[{"url":"https://cpaas.mittoapi.com"}],"paths":{"/2fa/send":{"post":{"summary":"Send an OTP","description":"Send a POST request for an OTP to be sent to a particular number.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["service","from","to","body"],"properties":{"service":{"type":"string","description":"The name of your service. For 2FA it will be 2FA.\n","example":"2FA"},"from":{"type":"string","description":"The phone number that is making the call, or sending the SMS containing the verification code.\n","example":"15555553309"},"to":{"type":"string","description":"The destination phone number to send the OTP message containing the verification code.\n","example":"15555558675"},"body":{"type":"string","description":"The content of the OTP message. Use {code} as a placeholder for the location of the verification code in your SMS content. This {code} will be replaced automatically with a random code generated by the system.\n","example":"Hello"},"channel":{"type":"string","description":"A method for sending an OTP message as sms or call or email. If not passed, default is SMS.\n"},"accountSid":{"type":"string","description":"The OTP message will be sent on behalf of the accountSid you provide. The accountSid has to be a valid sub-account. \n","example":"AC123461724187287abcbas791282cf"},"subject":{"type":"string","description":"Required for email channel use. This is the email subject for the OTP message, it’s required only in the email channel.\n","example":"OTP for login"},"language":{"type":"string","description":"If you choose to send a voice message, you would use this parameter to provide the Text-to-Speech (TTS) language tag for speaking the OTP message over the call channel. For a list of languages, see the Available Voices for TTS section. NOTE: This feature is available as a separately purchased add-on. If you only bought SMS capabilities you will not be able to use this.\n","example":"ro-RO\n"},"repeat":{"type":"string","description":"If you choose to send a voice message, you must specify the number of times the TTS OTP message will be played in the event that the user does not respond. It’s required for the call channel, but if you don’t enter a choice, it defaults to 1. NOTE: This feature is available as a separately purchased add-on. If you only bought SMS capabilities you will not be able to use this.\n","example":"3"},"length":{"type":"string","description":"You can specify the number of digits for the OTP code. If you do not specify something, by default a 6 digit number will be generated for the OTP code.\n","example":"7"},"voice":{"type":"string","description":"If you choose to send a voice message, you use this parameter with the language parameter. You specify whether you want a male or female voice. Choices for this parameter are: man, woman. Be sure a language is available with the voice gender you choose when you pick your language. For a list of languages and voice options, see the <a href=\"https://docs.mitto.ch/2fa-api-reference/\">Available Voices for TTS</a> section. NOTE: This feature is available as a separately purchased add-on. If you only bought SMS capabilities you will not be able to use this.\n","example":"man"},"timeout":{"type":"string","description":"You can choose the time in seconds for which an OTP is valid. Post timeout period, the OTP is automatically canceled if it is not successfully verified. The default is 300 seconds.\n","example":"430"},"guardTime":{"type":"string","description":"If you call the Send API again to send a new OTP with the same service (call or SMS) and the same parameters while the previously generated OTP is still valid, the previous OTP is cancelled, and the new OTP is sent. However, if the guardTime (in seconds) parameter is passed in the send request, the old OTP is valid for guardTime and then cancelled. This is to accommodate scenarios where the underlying SMS or call channel may be slow to deliver the message and by the time the new OTP is generated, the user might have received the old OTP.\nexample: '50'\n"},"limits":{"type":"string","description":"Key-Value pair Limits to restrict on number of OTP’s generated based on criteria that developers select.\n","example":"{ \"limit_on_ip\": \"127.0.0.1\", \"limit_on_phone\": \"+919960639901\" }\n"},"workflow":{"type":"string","description":"The workflow name to apply to the corresponding workflow template.\n","example":"Workflow SSV"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json; charset=utf-8":{"schema":{"$ref":"#/components/schemas/response_2fa"}}}},"400":{"description":"'Bad Request - \n* 451 - Mandatory parameter \"abc\" is missing - \"abc\" is the parameter name that is missing. If you are missing mutliple required parameters, you will get a list of comma separated parameter names. \n* 452 - Underlying message from Mitto - Error returned by underlying Mitto platform.\n"},"401":{"description":"'Unauthorized - \n* 401 - Validation failed - This error code appears if validation failed for the provdied accountSid and token.\n* 450 - AccountSid passed is wrong or not sub-account of account.\n"},"409":{"description":"'Conflict - \n* 453 - Too many OTP requests to the same destination number - This error occurs when an OTP is sent to the same destination number within 1 min of your previous send. The 2FA API limits the number of OTP sent to the same number to a maximum of one per min.\n* 497 - Invalid Limits. There is no Limit with name \"ZZZ\" - Send API is called with a Limits name that is not defined.\n* 505 - Invalid Workflow. - The API was caleld with a workflow name that is not defined. \n"}}}},"/2fa/verify":{"post":{"summary":"Verify an OTP","description":"After you send an OTP, you will want to verify the code. Use the verify an OTP endpoint to check that the user entered the right verification code.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["service","requestId","code"],"properties":{"service":{"type":"string","description":"The name of your service.\n","example":"2FA"},"requestId":{"type":"string","description":"The request ID that you received when initiating the OTP message.\n","example":"OTPYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"},"accountSid":{"type":"string","description":"If your OTP message was initiated on behalf of an accountSid, you must include the same accountSid to be able to verify the OTP request.\n","example":"AC123461724187287abcbas791282cf"},"code":{"type":"string","description":"The verification code that you sent to the user through SMS.\n"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json; charset=utf-8":{"schema":{"$ref":"#/components/schemas/response_2fa"}}}},"401":{"description":"Unauthorized - 474 Invalid OTP Code - Verify is called for an ID which is present and an invalid code is passed.\n"},"404":{"description":"Not Found - Invalid OTP - Verify is called for a request ID that doesn't exist.\n"},"409":{"description":"Conflict - 472 OTP is expired - Verify is called for an ID which exists, but is expired.\n"}}}},"/2fa/cancel":{"post":{"summary":"Cancel an OTP You Sent","description":"'Cancel an OTP that you sent. You must include the request ID for the specific OTP.'\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"The requestID was received when initiating an OTP message. \n"},"accountSid":{"type":"string","description":"If an OTP message was initiated on behalf of the accountSid, you must provide the same accountSid to be able to cancel the OTP request.\n"}}}}}},"responses":{"200":{"description":"Success"},"400":{"description":"* 451 Mandatory parameter zzz is missing - Occurs\n"},"401":{"description":"* 401 Validation failed - Occurs if validation fails for a provided accountSid and token.\n* 450 AccountSid passed is wrong or not a sub-account of account \"zzzzz\" - \"zzzzz\" is the accountSid passed in a validation request but is wrong or not a sub-account of accountSid passed in the authentication header.\n"},"404":{"description":"* 490 Invalid OTP Unique Id - Control (Cancel for now, but may be others too in the future) is called for a unique ID which is not present in-system.\n"},"409":{"description":"* 472 OTP is expired - Verify is called for Unique ID which is present in the system, but expired.\n* 473 OTP is cancelled - Verify is called for Unique ID which is present in the system, but cancelled.\n* 493 Invalid limit ID - Limit ID passed is not present in the system\n"}}}},"/2fa/search":{"post":{"summary":"Retrieve a Filtered List of Session Detail Records","description":"Use a POST request to submit details you want to use to narrow down the OTP sessions returned to you.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","description":"Which page of OTP records to return, starting from 0."},"pageSize":{"type":"integer","description":"Number of records returned per page."},"accountSid":{"type":"string","description":"Only include OTP list that is initiated by this specific account Sid. The accountSid should be one of the sub accounts of this account."},"subAccounts":{"type":"boolean","description":"If set to true, include the OTP list that is initiated by all the sub accoutns within the accountSid you provided."},"service":{"type":"boolean","description":"Only include OTPs in the list that match this service text, partially or fully in any position. For example if OTP service is “Support” and the service filter parameter is “ppo”, it will match."},"channel":{"type":"string","description":"Only include OTPs in the list that are initiated via this channel. Possible values are call, sms, email, or combined. Combined is for OTPs sent as part of a workflow."},"from":{"type":"string","description":"Only include OTPs in the list that have a from which begins with this number or email. For example, if an OTP is sent from ‘15713316943’ and the from filter parameter is ‘1’, it will match. However if the from filter parameter is ‘3’, this record will not match. This allows you to filter for OTPs sent from a specific country code."},"to":{"type":"string","description":"Only include OTPs in the list if they begin with this number/email. For example, if the OTP’s ‘to’ is ‘16513333367’ and the to filter parameter is ‘1’, it will match. However if the to filter parameter is ‘3’, this record will not match. This allows you to filter the sent OTP to specific country codes."},"targetSid":{"type":"string","description":"Only include OTPs in the list that match the target sid of SMS, Call or Email provided, partially or fully in any position."},"status":{"type":"string","description":"Only include OTPs in the list that have this status. Possible values are success, cancelled, or expired."},"startTime":{"type":"string","description":"Only show OTPs in the list that were created on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2019-10-05T22:45:32) or if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in the UTC timezone."},"endTime":{"type":"string","description":"Only show OTPs in the list that were created on this date/time or earlier, given as an ISO-8601date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in the UTC timezone."},"channelStatus":{"type":"string","description":"Only include OTPs in the list that match the underlying channel status, partially or fully in any position. Available statuses for channels are -\n* SMS - sending, sent, failed, received, delivered, and undelivered\n* CALL - queued, ringing, in-progress, completed, failed, busy, and no-answer \n"}}}}}},"responses":{"200":{"description":"Success"}}},"get":{"summary":"Retrieve All Session Detail Records Parameters.","description":"You can send a GET request if you want to retrieve session details for every 2FA sent. You can also use SortBy with the GET method to determine which attributes you want to sort by and in which direction. Directions include - \n* asc - ascending\n* desc - descending \nAnd in an example, it would be https://cpaas.mittoapi.com/2fa/search?sortBy=sorting attribute:asc where sorting attribute is DateCreated, Service, or Status\n","responses":{"200":{"description":"Success"}}}},"/2fa/search/{OTPSid}":{"get":{"summary":"Retrieve Session Information by OTP Sid","description":"'OTPSid is the unique ID that comes back n the response when you send an OTP. The ID is referred to as the requestID.'\n","parameters":[{"name":"OTPSid","in":"path","required":true,"x-nullable":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sid":{"description":"OTP unique ID that was returned when the send API endpoint was called."}}}}}},"responses":{"200":{"description":"Success"}}}}},"components":{"schemas":{"response_2fa":{"type":"object","properties":{"code":{"type":"string","description":"Sub error code for the request.\n"},"message":{"type":"string","description":"Message for describing the sub error. \n"},"requestID":{"type":"string","description":"The unique OTP request identifier for the OTP request. \n"}}}},"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}}},"security":[{"basicAuth":[]}]}