Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1017 lines (999 sloc) 33.4 KB
openapi: 3.0.0
info:
title: 2FA API
description: >
Two-factor authentication (2FA) is an additional security layer for your
applications or your business.
Traditional username/password approach is vulnerable, especially on the today's environment where everything is online.
2FA aims to increase the security level of a standard password-only approach.
version: "1.0"
contact:
name: tyntec API Support
url: http://www.tyntec.com/support
email: support@tyntec.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0
x-repository: https://github.com/tyntec/api-collection/blob/master/2fa
x-major-version: v1
servers:
- url: https://api.tyntec.com
security:
- APIKeyHeader: []
tags:
- name: Application Service
description: >
Users can create multiple 2FA applications and configurations through the
2FA API.
tyntec stores these configurations so that users can select between own 2FA applications
and the corresponding linked configuration. Those configuration will be used
when delivering One Time Passwords (OTP).
There is a default 2FA application for each user which contains default values and English language template.
This default application will be used in case no 2FA application ID is specified in an OTP delivery request.
Default 2FA application is configurable and users can set own default parameters or 2FA application.
- name: OTP Service
description: The OTP service is used for delivering and checking One Time Password
(OTP) codes to destination numbers.
paths:
/2fa/v1/application:
get:
tags:
- Application Service
summary: Returns all applications created.
description: Return a list of applications that have been created under your account
operationId: getTwoFactorAuthApplicationsUsingGET
responses:
"200":
description: The list of applications
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/TwoFactorAuthApplicationEntity"
"204":
description: Empty list. No applications found for your account
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/TwoFactorAuthApplicationEntity"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
post:
tags:
- Application Service
summary: Create 2FA application
description: |
Creates a 2FA application instance. You can either:
- Use the target URI with a POST HTTP request
- Include the application parameters in your request body
Values that are not defined will be populated with default values.
operationId: createTwoFactorAuthApplicationUsingPOST
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/TwoFactorAuthApplicationEntity"
description: The application to be created.
responses:
"200":
description: The new application created
content:
application/json:
schema:
$ref: "#/components/schemas/TwoFactorAuthApplicationEntity"
"400":
description: Not valid configuration provided
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
Wrong PIN length:
examples:
response:
value:
message: PIN length should be between 4 to 10 digits
code: "1006"
timestamp: 1498730218449
Wrong expiration time:
examples:
response:
value:
message: Number of expiration should be between 30 and 7200
code: "1008"
timestamp: 1498730687525
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/2fa/v1/application/{applicationId}":
get:
tags:
- Application Service
summary: Returns a 2FA application
description: You can get a specific application by using the GET HTTP method and the
application’s Universally Unique ID (UUID)
operationId: getTwoFactorAuthApplicationUsingGET
parameters:
- name: applicationId
in: path
description: Application ID to be returned
required: true
schema:
type: string
responses:
"200":
description: The application is included in the response
content:
application/json:
schema:
$ref: "#/components/schemas/TwoFactorAuthApplicationEntity"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: The id for this application is not valid
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
post:
tags:
- Application Service
summary: Edit 2FA application
description: Define the parameters that you would like to change in a 2FA application
operationId: updateTwoFactorAuthApplicationUsingPOST
parameters:
- name: applicationId
in: path
description: This parameter is part of the URI following the pattern
${baseURL}/application/{applicationId}. You can specify "default" to
reference the default application
required: true
schema:
type: string
- name: name
in: query
description: This parameter represents the custom name for this application.
“default” is not allowed, since it is reserved as it maps to the
default application for this user.
required: false
schema:
type: string
- name: pinLength
in: query
description: The length of the auto generated PIN length. PIN length can be
between 4-11 digits.
required: false
schema:
type: integer
format: int32
- name: alphaNumeric
in: query
description: By default this parameter is FALSE, and the PIN is generated in
numeric values. In case this parameter is TRUE then the
auto-generated PIN will be a lower case alphanumeric PIN.
required: false
schema:
type: boolean
- name: attempts
in: query
description: This parameter controls how many attempts the user is allowed to
have in order to validate a delivered OTP.
required: false
schema:
type: integer
format: int32
- name: expire
in: query
description: This parameter controls the expiration time in seconds after the
first OTP delivery request.
required: false
schema:
type: integer
format: int64
- name: sender
in: query
description: This parameter is controlling the sender name upon SMS delivery.
required: false
schema:
type: string
- name: caller
in: query
description: This parameter is used to define a number as caller for voice calls.
Adding this will improve the call success ratio, as some operators
filters anonymous calls.
required: false
schema:
type: string
- name: deleteCaller
in: query
description: This parameter is used to delete an already defined caller for voice
calls.
required: false
schema:
type: boolean
responses:
"200":
description: The application is included in the response
content:
application/json:
schema:
$ref: "#/components/schemas/TwoFactorAuthApplicationEntity"
"201":
description: Created
"400":
description: Not valid configuration provided
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: The id for this application is not valid
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Something went wrong :-(
delete:
tags:
- Application Service
summary: Delete 2FA application
description: >
You can delete your application if needed by using the DELETE HTTP
method. Existing OTPs will still be valid but resend or verification of
an OTP will not be possible.
**Note** You cannot delete the “default” application.
operationId: deleteTwoFactorAuthApplicationUsingDELETE
parameters:
- name: applicationId
in: path
description: Application ID to be deleted
required: true
schema:
type: string
responses:
"200":
description: The application was deleted
content:
application/json:
schema:
$ref: "#/components/schemas/TwoFactorAuthApplicationEntity"
"204":
description: No Content
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: The id for this application is not valid
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Something went wrong :-(
"/2fa/v1/application/{applicationId}/language":
post:
tags:
- Application Service
summary: Add/Update language template
description: You can add or edit a language template by referring to the application
UUID resource and the language you want to add or edit. If you specify
also the channel optional parameter, the specific template for this
delivery channel will be created.
operationId: saveLanguageTwoFactorAuthApplicationUsingPOST
parameters:
- name: applicationId
in: path
description: The applicationId of the application you would like to edit. This
parameter is part of the URI following the pattern
${baseURL}/application/{applicationId}. You can specify "default" to
reference the default application
required: true
schema:
type: string
- name: language
in: query
description: The language locale should be in [ISO
639-1](https://en.wikipedia.org/wiki/ISO_639-1) format
required: true
schema:
type: string
- name: text
in: query
description: The text template for the specific language. Placeholder {{OTP}}
must exist at least once. {{SEC}} is an optional placeholder that
will replace the “expire” parameter for this application.
required: true
schema:
type: string
- name: channel
in: query
required: false
description: This optional parameter is set in case you want to have different
template for the same language, depending on the delivery channel,
SMS or VOICE
schema:
type: string
responses:
"200":
description: The application language template has been saved
content:
application/json:
schema:
$ref: "#/components/schemas/TwoFactorAuthApplicationEntity"
"201":
description: Created
"400":
description: Wrong arguments provided
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: The id for this application is not valid
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
delete:
tags:
- Application Service
summary: Delete language template
description: >
You can delete a language template by referring to the application UUID
resource and the language you want to delete.
If you specify also the channel optional parameter, the specific template for this delivery channel will be deleted.
operationId: deleteLanguageTwoFactorAuthApplicationUsingDELETE
parameters:
- name: applicationId
in: path
description: This parameter is the applicationId of the application you would
like to edit and it is part of the URI following the pattern
${baseURL}/application/{applicaitonId}. You can specify "default" to
reference the default application
required: true
schema:
type: string
- name: language
in: query
description: The language locale should be in [ISO
639-1](https://en.wikipedia.org/wiki/ISO_639-1) format
required: true
schema:
type: string
- name: channel
in: query
required: false
description: This optional parameter is set in case you want to have different
template for the same language, depending on the delivery channel,
SMS or VOICE
schema:
type: string
responses:
"200":
description: The language template was deleted
content:
application/json:
schema:
$ref: "#/components/schemas/TwoFactorAuthApplicationEntity"
"204":
description: No Content
"400":
description: Wrong arguments provided
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: The id for this application is not valid, or language does not exist
"500":
description: Something went wrong :-(
/2fa/v1/otp:
get:
tags:
- OTP Service
summary: Get all OTPs
description: You can query the events endpoint of an OTP delivery instance to get
back a list of events reported for this delivery.
operationId: getOtpsForNumberUsingGET
parameters:
- name: number
in: query
description: The destination telephone number in
[E.164](https://en.wikipedia.org/wiki/E.164) format
required: true
schema:
type: string
responses:
"200":
description: The list of OTPs
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/OtpStatusEntity"
"204":
description: Empty list. No OTPs found for this account
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/OtpStatusEntity"
"400":
description: Invalid number format provided
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
post:
tags:
- OTP Service
summary: Sends OTP
description: Send an OTP based on your application configuration. Modify the request
based on the optional parameters.
operationId: sendOtpForNumberUsingPOST
parameters:
- name: number
in: query
description: The destination telephone number in
[E.164](https://en.wikipedia.org/wiki/E.164) format
required: true
schema:
type: string
- name: applicationId
in: query
description: The UUID of the application you want to use. If not specified, the
default will be used.
required: false
schema:
type: string
- name: via
in: query
description: SMS/VOICE/AUTO. The channel to deliver the OTP
required: false
schema:
type: string
default: AUTO
- name: country
in: query
description: >
Optional if you provided a number without country code, it will add
automatically.
If the country code is included but doesn't match the country specified, it will result to an error
required: false
schema:
type: string
- name: language
in: query
description: The language template to be used in [ISO
639-1](https://en.wikipedia.org/wiki/ISO_639-1) codes. If the
template is not specified it will be auto detected based on number.
If a language template does not exist, it will default to English
required: false
schema:
type: string
- name: text
in: query
description: Text to override the default template. Placeholder {{OTP}} must
exist for auto generation of OTP, otherwise otpCode should be
specified
required: false
schema:
type: string
- name: referenceId
in: query
description: Set your custom reference ID
required: false
schema:
type: string
- name: otpCode
in: query
description: Override the auto generated OTP code
required: false
schema:
type: string
- name: sender
in: query
description: Override the applications sender
required: false
schema:
type: string
- name: caller
in: query
description: Override the applicaitons caller
required: false
schema:
type: string
- name: pinLength
in: query
description: The length of the auto generated PIN length. PIN length can be
between 4-11 digits.
required: false
schema:
type: string
responses:
"200":
description: The result of the OTP with a unique ID
content:
application/json:
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"*/*":
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"201":
description: Created
"400":
description: Invalid parameters provided. Look at the response for the specific
error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"*/*":
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: Not Found
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"*/*":
schema:
$ref: "#/components/schemas/ErrorResponse"
"/2fa/v1/otp/{otpId}":
get:
tags:
- OTP Service
summary: OTP status
description: Returns the status of an OTP.
operationId: getOtpStatusUsingGET
parameters:
- name: otpId
in: path
description: The OTP ID that the code should be resent
required: true
schema:
type: string
responses:
"200":
description: The OTP status
content:
application/json:
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: OTP code not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
post:
tags:
- OTP Service
summary: Resend an OTP
description: >
In case the end user didn’t receive the OTP in a reasonable timeframe
you can use this operation to resend the same OTP code.
The OTP code will be the same as the original one, but you have the option to choose a different delivery channel.
operationId: resendOtpStatusUsingPOST
parameters:
- name: otpId
in: path
description: The OTP ID that the code should be resent
required: true
schema:
type: string
- name: via
in: query
description: You can force a delivery channel by using this parameter. Posible
values are AUTO, SMS or VOICE. The default is “AUTO” which will use
SMS in case of a mobile number and VOICE in case of a landline
number.
required: false
schema:
type: string
default: AUTO
- name: sender
in: query
description: In case you want to override the sender set in the application's
configuration, you can specify a sender name for this OTP delivery
required: false
schema:
type: string
- name: caller
in: query
description: In case you want to override the caller set in the application's
configuration, you can specify a caller id for this OTP delivery
required: false
schema:
type: string
responses:
"200":
description: OTP resend
content:
application/json:
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"201":
description: Created
"400":
description: Not valid parameter provided
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
description: OTP is not valid anymore
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"403":
description: Forbidden
"404":
description: OTP not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
delete:
tags:
- OTP Service
summary: Delete OTP
description: You can delete the status of an OTP by using this operation
operationId: deleteOtpStatusUsingDELETE
parameters:
- name: otpId
in: path
description: The OTP ID that the code should be resent
required: true
schema:
type: string
responses:
"200":
description: OTP deleted
content:
application/json:
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"204":
description: No Content
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: OTP not found
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"/2fa/v1/otp/{otpId}/events":
get:
tags:
- OTP Service
summary: OTP events status
operationId: getOtpEventsUsingGET
description: You can query the events endpoint of an OTP delivery instance to get
back a list of events reported for this delivery.
parameters:
- name: otpId
in: path
description: The OTP ID that the code should be resent
required: true
schema:
type: string
responses:
"200":
description: The OTP status
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/StatusEvent"
"*/*":
schema:
type: array
items:
$ref: "#/components/schemas/StatusEvent"
"401":
description: Unauthorized
"403":
description: Forbidden
"404":
description: OTP code not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"*/*":
schema:
$ref: "#/components/schemas/ErrorResponse"
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"*/*":
schema:
$ref: "#/components/schemas/ErrorResponse"
"/2fa/v1/otp/{otpId}/check":
post:
tags:
- OTP Service
summary: OTP Validate
description: >
This operation will verify if the OTP code used matched the OTP code
that was generated for this user.
To verify an OTP code, you need to provide
1) the unique OTPId that refers the the OTP delivery request
2) the OTP code sent to the user
operationId: checkOtpUsingPOST
parameters:
- name: otpId
in: path
description: The OTP ID that the code should be resent
required: true
schema:
type: string
- name: otpCode
in: query
description: otpCode
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"201":
description: Created
"202":
description: OTP provided is valid
content:
application/json:
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"401":
description: OTP code provided is not valid
content:
application/json:
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"403":
description: OTP has been expired of too many attempts already
content:
application/json:
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"404":
description: OTP not found
"410":
description: OTP is not active anymore
content:
application/json:
schema:
$ref: "#/components/schemas/OtpStatusEntity"
"500":
description: Something went wrong :-(
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
components:
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: apiKey
schemas:
OtpStatusEntity:
type: object
description: OTP Status schema
properties:
accountId:
description: This is your 2FA accountId in the tyntec system. You cannot change
this value
type: string
applicationId:
description: The Universally Unique ID (UUID) that identifies the specific
application used to deliver this OTP
type: string
attemptCount:
description: The number of attempts made for this OTP to be validated
type: integer
format: int32
created:
description: The time that the OTP request was created in milliseconds
type: integer
format: int64
expire:
description: The time that the OTP will expire in milliseconds
type: integer
format: int64
number:
description: The destination telephone number in
[E.164](https://en.wikipedia.org/wiki/E.164) format
type: string
otpId:
description: The OTP ID that the code should be resent
type: string
otpStatus:
description: >
The OTP status. Possible values, ACTIVE, when the OTP is still
active; VERIFIED, when the OTP was verified successfully;
EXPIRED, when the OTP expired; TOO_MANY_ATTEMPTS, when the OTP validation requests exceeded the maximum allowed by the application configuration.
type: string
referenceId:
description: Set your custom reference ID
type: string
timestampCreated:
description: The string timestamp “created” representation in UTC Z format
type: string
timestampExpire:
description: The string timestamp “expire” representation in UTC Z format
type: string
StatusEvent:
type: object
description: Status schema
properties:
created:
description: Timestamp in [Epoch/Unix
time](https://en.wikipedia.org/wiki/Unix_time)
type: integer
format: int64
status:
description: Event status. Possible values success/failed/null
type: string
statusText:
description: The status reported by the deivery system
type: string
timestampCreated:
description: The string timestamp “created” representation in UTC Z format
type: string
type:
description: Refere to the next table regarding all event types
type: string
TwoFactorAuthApplicationEntity:
type: object
description: Two Factor Authentication Application structure
properties:
alphanumeric:
type: boolean
example: false
description: If the OTP is alphanumeric or not
attempts:
type: integer
format: int32
example: 3
description: How many attempts the user can have for this OTP
expire:
type: integer
format: int64
example: 300
description: How many seconds until OTP expires
name:
type: string
description: Custom application name
pinLength:
type: integer
format: int32
description: The length of the auto generated PIN length. PIN length can be
between 4-11 digits.
example: 4
sender:
type: string
example: VERIFY
description: The sender used for SMS delivery
caller:
type: string
example: VERIFY
description: The caller used for TTS delivery. Using a valid number will improve
filtering issues caused by anonymous calls
ErrorResponse:
type: object
description: Error Response schema
properties:
code:
description: The reason for an unsuccessful attempt
type: string
id:
description: Error code ID
type: string
message:
description: Textual representation of the code, containing further information
type: string
timestamp:
description: Timestamp in [Epoch/Unix
time](https://en.wikipedia.org/wiki/Unix_time)
type: integer
format: int64
You can’t perform that action at this time.