Last active
December 6, 2019 14:30
-
-
Save amilos/f776838ede133e9bfb938454ba96d31d to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| swagger: '2.0' | |
| x-asee-visibility: public | |
| info: | |
| description: Multifactor Authentication API enables authentication of users and signing of sensitive transactions using token based credentials or random one-time verification code sent to pre-registered email account or mobile number. Authentication and signatures using token based credentials follow OATH standard HOTP, TOTP and OCRA algorithms or their proprietary alternatives. Initiation of out-of-band authentication and signature flows is possible with images (QR code) and push messages. | |
| title: Multifactor Authentication API | |
| version: beta | |
| host: bankapi.net | |
| basePath: /beta/mfa | |
| tags: | |
| - description: One-time code to verify proof of control over phone number or email address | |
| name: OTC | |
| - description: One-time passwords | |
| name: OTP | |
| - description: Challenge-response authentication | |
| name: CR | |
| - description: Electronic signature | |
| name: SIG | |
| - description: User profile with assigned tokens | |
| name: Userinfo | |
| - description: Multi-factor authentication capabilities | |
| name: Capabilities | |
| - description: Callback notifications to calling application | |
| name: Callback | |
| consumes: | |
| - application/json | |
| produces: | |
| - application/json | |
| schemes: | |
| - https | |
| - http | |
| paths: | |
| /otc/send: | |
| post: | |
| summary: Send one-time code to receipient | |
| description: Generates one-time verification code and sends it to specific receipient via SMS or email | |
| tags: | |
| - OTC | |
| x-asee-tags: [] | |
| operationId: OTC_Send | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Instruction to send OTC | |
| in: body | |
| name: cmd | |
| required: true | |
| schema: | |
| $ref: '#/definitions/send-otc-command' | |
| responses: | |
| 202: | |
| description: OTC Sent | |
| schema: | |
| $ref: '#/definitions/verification-id' | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Request was well formed but **OTC could not be sent**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [user-not-recognized]() | User was not recognized | | |
| | [phone-number-not-recognized]() | Phone number was not recognized | | |
| | [email-address-not-recognized]() | Email address was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /otc/verify: | |
| post: | |
| operationId: OTC_Verify | |
| summary: Verify OTC | |
| description: Verifies one-time code delivered to user over SMS or email. Original OTC request is correlated using `verification-id`, `email-address` or `phone-number` | |
| tags: | |
| - OTC | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Request to verify OTC | |
| in: body | |
| name: req | |
| required: true | |
| schema: | |
| $ref: '#/definitions/verify-otc-request' | |
| responses: | |
| 204: | |
| description: OTC is valid | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Request was well formed but OTP could not be verified. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [invalid-otc]() | One-time code is not valid | | |
| | [replayed-otc]() | One-time code was replayed | | |
| | [verification-not-recognized]() | Verification was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| | [phone-number-not-recognized]() | Phone number was not recognized | | |
| | [email-address-not-recognized]() | Email address was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /otp/validate: | |
| post: | |
| operationId: OTP_Validate | |
| summary: Validate OTP | |
| description: Validates OTP for specific user or token. For OATH compliant tokens, validation is performed according to OATH HOTP and TOTP validation server profile. | |
| tags: | |
| - OTP | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Request with details to validate OTP | |
| in: body | |
| name: req | |
| required: true | |
| schema: | |
| $ref: '#/definitions/validate-otp-request' | |
| responses: | |
| 204: | |
| description: No content - OTP is valid | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Your request was well formed but **OTP could not be verified**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [invalid-otp]() | One-time password is not valid | | |
| | [token-not-recognized]() | Token was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /challenge: | |
| post: | |
| operationId: CR_ComputeChallenge | |
| summary: Compute CR challenge | |
| description: Computes a challenge for CR authentication. Algorithms follow the profile of the token. For OATH compliant tokens, hashing and formatting is performed according to OCRA validation server profile. | |
| tags: | |
| - CR | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Instruction to compute CR challenge | |
| in: body | |
| name: req | |
| required: true | |
| schema: | |
| $ref: '#/definitions/compute-cr-challenge-request' | |
| responses: | |
| 200: | |
| description: CR challenge generated | |
| schema: | |
| $ref: '#/definitions/challenge' | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Your request was well formed but **CR challenge could not be generated**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [token-not-recognized]() | Token was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /signature: | |
| post: | |
| operationId: SIG_ComputeSignatureChallenge | |
| summary: Compute signature challenge | |
| description: Computes a signature challenge. Algorithms follow the profile of the token. For OATH compliant tokens, concatenation, hashing and formatting is performed according to OCRA validation server profile. | |
| tags: | |
| - SIG | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Instruction to compute signature challenge | |
| in: body | |
| name: req | |
| required: true | |
| schema: | |
| $ref: '#/definitions/compute-signature-challenge-request' | |
| responses: | |
| 200: | |
| description: Signature challenge generated | |
| schema: | |
| $ref: '#/definitions/challenge' | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Your request was well formed but **Signature challenge could not be generated**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [token-not-recognized]() | Token was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /otp/image: | |
| post: | |
| operationId: OTP_GenerateAuthenticationImage | |
| summary: Generate authentication challenge as image | |
| description: Generates image that will be decoded by user's token app for authentication. For OATH compliant tokens, OTP follows HOTP or TOTP specification. Generated image contains display metadata encoded according to scheme such as `QR code` in image format such as `image/jpg`. Once the user authentication is confirmed MFA server will call the appropriate callback supplied by the application. | |
| tags: | |
| - OTP | |
| x-asee-tags: [] | |
| produces: | |
| - image/png | |
| - image/jpg | |
| - image/gif | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Instruction to generate authentication challenge as image | |
| in: body | |
| name: cmd | |
| required: true | |
| schema: | |
| $ref: '#/definitions/generate-authentication-image-command' | |
| responses: | |
| 200: | |
| description: OK - Authentication image generated | |
| schema: | |
| type: file | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Your request was well formed but **authentication image could not be generated**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [token-not-recognized]() | Token was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /otp/push: | |
| post: | |
| operationId: OTP_InitiateAuthenticationPush | |
| summary: Initiate authentication with push message | |
| description: Initiates authentication with push message sent to user's mobile token app. For OATH compliant tokens, OTP conforms to HOTP or TOTP specification. Push message contains metadata that can be interpreted by user's mobile token app. Once the user authentication is confirmed MFA server will call the appropriate callback supplied by the application. | |
| tags: | |
| - OTP | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Instruction to initiate authentication push message | |
| in: body | |
| name: cmd | |
| required: true | |
| schema: | |
| $ref: '#/definitions/initiate-authentication-push-message-command' | |
| responses: | |
| 204: | |
| description: Push authentication initiated | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Your request was well formed but **Authentication challenge push could not be initiated**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [token-not-recognized]() | Token was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /signature/image: | |
| post: | |
| operationId: SIG_InitiateSignatureImage | |
| summary: Initiate signature challenge as image | |
| description: Computes an signature challenge and generates image that will be decoded by user's token app for confirmation of a sensitive transaction. For OATH compliant tokens, challenge is computed and formatted according to OCRA validation server profile. Challenge is then combined with additional metadata and encoded according to scheme such as `QR code` in image format such as `image/jpg`. Once the transaction is confirmed MFA server will call the appropriate callback supplied by the application. | |
| tags: | |
| - SIG | |
| x-asee-tags: [] | |
| produces: | |
| - image/png | |
| - image/jpg | |
| - image/gif | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Instruction to generate signature challenge image | |
| in: body | |
| name: cmd | |
| required: true | |
| schema: | |
| $ref: '#/definitions/generate-signature-image-command' | |
| responses: | |
| 200: | |
| description: OK - Signature image generated | |
| schema: | |
| type: file | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Your request was well formed but **Signature image could not be generated**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [token-not-recognized]() | Token was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /signature/push: | |
| post: | |
| operationId: SIG_InitiateSignaturePush | |
| summary: Initiate signature with push message | |
| description: Computes a signature challenge and sends push message to user's mobile token app for confirmation of a sensitive transaction. For OATH compliant tokens, challenge is computed and formatted according to OCRA validation server profile. Challenge is then combined with additional metadata and formatted as a push message that can be interpreted by user's mobile token app. Once the transaction is confirmed MFA server will call the appropriate callback supplied by the application. | |
| tags: | |
| - SIG | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Instruction to initiate signature push challenge | |
| in: body | |
| name: cmd | |
| required: true | |
| schema: | |
| $ref: '#/definitions/initiate-signature-push-message-command' | |
| responses: | |
| 204: | |
| description: Push challenge initiated | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Your request was well formed but **Signature challenge push could not be initiated**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [token-not-recognized]() | Token was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /signature/verify: | |
| post: | |
| operationId: SIG_VerifySignature | |
| summary: Verify signature response | |
| description: Verifies signature response | |
| tags: | |
| - SIG | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Request to verify signature response | |
| in: body | |
| name: req | |
| required: true | |
| schema: | |
| $ref: '#/definitions/verify-signature-request' | |
| responses: | |
| 204: | |
| description: No content - signature response is valid | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Your request was well formed but **Signature response could not be verified**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [invalid-response]() | One-time password is not valid | | |
| | [replayed-response]() | One-time password was replayed | | |
| | [token-not-recognized]() | Token was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /response/verify: | |
| post: | |
| operationId: CR_VerifyResponse | |
| summary: Verify CR response | |
| description: Verifies response to a challenge | |
| tags: | |
| - CR | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Request to verify CR response | |
| in: body | |
| name: req | |
| required: true | |
| schema: | |
| $ref: '#/definitions/verify-response-request' | |
| responses: | |
| 204: | |
| description: No content - CR response is valid | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 422: | |
| description: | | |
| Your request was well formed but **CR response could not be verified**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [invalid-response]() | One-time password is not valid | | |
| | [replayed-response]() | One-time password was replayed | | |
| | [token-not-recognized]() | Token was not recognized | | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /capabilities: | |
| get: | |
| operationId: Capabilities_Get | |
| summary: Query MFA server capabilities | |
| description: Returns capabilities supported by MFA server | |
| tags: | |
| - Capabilities | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| responses: | |
| 200: | |
| description: OK | |
| schema: | |
| $ref: '#/definitions/capabilities' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /userinfo/{user-id}: | |
| get: | |
| operationId: Userinfo_Get | |
| summary: Get MFA profile of user | |
| description: Returns MFA profile of specific user with list of assigned tokens and allowed MFA methods | |
| tags: | |
| - Userinfo | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Unique identifier of the user recognized by MFA server | |
| in: path | |
| name: user-id | |
| required: true | |
| type: string | |
| responses: | |
| 200: | |
| description: OK | |
| schema: | |
| $ref: '#/definitions/userinfo' | |
| 422: | |
| description: | | |
| Your request was well formed but **user infomration could not be returned**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [user-not-recognized]() | User was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /oob-confirmation-callback-url: | |
| post: | |
| operationId: HandleConfirmationNotification | |
| summary: Notification of out-of-band transaction confirmation | |
| description: | | |
| Handles notification of out-of-band confirmation of a sensitive transaction. | |
| > **IMPORTANT:** This method must be implemented by application that initiates the confirmation using image or push message. The callback url is supplied to validation server in initiation request. | |
| tags: | |
| - Callback | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Notification with out-of-band confirmation of transaction | |
| in: body | |
| name: payload | |
| required: true | |
| schema: | |
| $ref: '#/definitions/oob-confirmation-notification' | |
| responses: | |
| 204: | |
| description: Notification acknowledged | |
| 401: | |
| description: Unauthorized | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 404: | |
| description: Not found | |
| 405: | |
| description: Method not allowed | |
| 413: | |
| description: Payload too large | |
| 415: | |
| description: Unsupported media type | |
| 422: | |
| description: | | |
| Your notification was well formed but it **could not be handled**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [transaction-not-recognized]() | Transaction was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| 500: | |
| description: Internal server error | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| /oob-authentication-callback-url: | |
| post: | |
| operationId: HandleAuthenticationNotification | |
| summary: Notification of out-of-band authentication | |
| description: | | |
| Handles notification of out-of-band authnentication. | |
| > **IMPORTANT:** This method must be implemented by application that initiates the authentication using image or push message. The callback url is supplied to validation server in initiation request. | |
| tags: | |
| - Callback | |
| x-asee-tags: [] | |
| parameters: | |
| - description: Unique identifier of http request | |
| in: header | |
| name: X-Request-ID | |
| type: string | |
| required: true | |
| format: uuid | |
| - description: Unique identifier of tenant recognized by MFA server. Mandatory in multi-tenant MFA installation, optional otherwise. | |
| in: header | |
| name: X-Tenant-ID | |
| type: string | |
| required: false | |
| - description: Notification with out-of-band authentication | |
| in: body | |
| name: payload | |
| required: true | |
| schema: | |
| $ref: '#/definitions/oob-authentication-notification' | |
| responses: | |
| 204: | |
| description: Notification acknowledged | |
| 401: | |
| description: Unauthorized | |
| 400: | |
| $ref: '#/responses/validation-problem-response' | |
| 404: | |
| description: Not found | |
| 405: | |
| description: Method not allowed | |
| 413: | |
| description: Payload too large | |
| 415: | |
| description: Unsupported media type | |
| 422: | |
| description: | | |
| Your notification was well formed but it **could not be handled**. Consider the following possible problems and look into response for more details: | |
| | Problem code | Decription | | |
| |---------------------------------------|---------------------------------------| | |
| | [transaction-not-recognized]() | Transaction was not recognized | | |
| schema: | |
| $ref: '#/definitions/problem' | |
| 500: | |
| description: Internal server error | |
| default: | |
| $ref: '#/responses/default-error-response' | |
| parameters: {} | |
| definitions: | |
| # PROBLEM MODELS | |
| problem: | |
| description: Details on specific problem that prevented processing after successfull validation | |
| type: object | |
| properties: | |
| problem: | |
| description: Unique literal that identifies specific problem | |
| type: string | |
| message: | |
| description: Message explaining the situation and optionaly remedies | |
| type: string | |
| details: | |
| description: Optional details supplied for troubleshooting | |
| type: string | |
| example: | |
| problem: document-locked | |
| message: Document you are trying to access is locked by another user | |
| details: User john.doe has locked the document | |
| validation-problem: | |
| description: Details of failed validation | |
| properties: | |
| errors: | |
| description: List of validation errors | |
| type: array | |
| items: | |
| type: object | |
| properties: | |
| tag: | |
| description: Name of input element (field or parameter) that is in invalid. If missing or null it is interpreted that validation error refers to entire request rather than to specific element. | |
| type: string | |
| error: | |
| description: Unique literal that identifies kind of validation error | |
| type: string | |
| message: | |
| description: Message that explains failed validation. To support translation message may embed variable parameters in curly brackets. | |
| type: string | |
| example: | |
| errors: | |
| - | |
| tag: phone-number | |
| error: invalid-format | |
| message: Format for this field is invalid | |
| - | |
| tag: phone-number | |
| error: max-length | |
| message: Content exceeds maximum alowed length | |
| - | |
| tag: account-number | |
| error: check-digit-invalid | |
| message: Check digit is invalid for this field | |
| # REQUESTS AND COMMAND MODELS | |
| send-otc-command: | |
| description: Instruction to send one-time code to recepient | |
| required: | |
| - via | |
| properties: | |
| via: | |
| type: string | |
| description: The method of delivering the code to the user. `sms` or `email` | |
| enum: [sms, email] | |
| user-id: | |
| type: string | |
| description: Optional unique identifier of the user who is receiving OTC. If present, preconfigured phone number or email address will be used. | |
| phone-number: | |
| type: string | |
| format: E.164 | |
| description: Optional phone number that will receive OTC. Format must conform to E.164 ITU-T recommendation. Mandatory when `via` value is `sms` and `user-id` is not present. | |
| email-address: | |
| type: string | |
| format: email | |
| description: Optional email address of the receipient OTC. Mandatory when `via` value is `email` and `user-id` is not present. | |
| action: | |
| type: string | |
| description: Optional service code of sensitive action that is authenticated such as `sign-in` | |
| message-content: | |
| type: string | |
| description: Optional content to include in message sent to user | |
| example: | |
| via: "sms" | |
| user-id: "nodjo-001" | |
| action: "sign-in" | |
| message: "Use the following code to sign-in to ABC app in next 30 seconds" | |
| phone-number: "+442071838750" | |
| verify-otc-request: | |
| description: Request with details to verify OTC | |
| required: | |
| - verification-id | |
| - otc | |
| properties: | |
| verification-id: | |
| description: Unique identifier of OTC verification in progress. The MFA server will use this identifier to match validate OTC. | |
| type: string | |
| format: uuid | |
| otc: | |
| type: string | |
| description: Digits or letters user users received via SMS or email | |
| minLength: 4 | |
| maxLength: 8 | |
| example: | |
| verification-id: "b8ebcd40-1234-5678-3fb5-0e5d6a065904" | |
| otp: "123456" | |
| validate-otp-request: | |
| description: Request with details to verify HOTP or TOTP | |
| required: | |
| - otp | |
| properties: | |
| user-id: | |
| type: string | |
| description: For existing user (customer or agent). Mandatory if `token-sn` is not present. | |
| otp: | |
| $ref: "#/definitions/token-otp" | |
| example: | |
| user-id: "nodjo-001" | |
| token-dn: "ASMT0000FFFE" | |
| otp: "123456" | |
| verify-response-request: | |
| required: | |
| - response | |
| - challenge | |
| description: Request to verify CR response | |
| properties: | |
| user-id: | |
| type: string | |
| description: For existing user (customer or agent) | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| challenge: | |
| $ref: "#/definitions/challenge" | |
| response: | |
| $ref: "#/definitions/token-otp" | |
| example: | |
| tokon-sn: "ASMT0000FFFE" | |
| challenge: | |
| challenge-id: "b8ebcd40-1234-5678-3fb5-0e5d6a065904" | |
| challenge: "d57d919d11e6b882028f9221c9bf6f7c882028f9" | |
| response: "123456" | |
| verify-signature-request: | |
| required: | |
| - response | |
| - challenge | |
| description: Request to verify signature response | |
| properties: | |
| user-id: | |
| type: string | |
| description: For existing user (customer or agent) | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| challenge: | |
| $ref: "#/definitions/challenge" | |
| response: | |
| $ref: "#/definitions/token-otp" | |
| example: | |
| tokon-sn: "ASMT0000FFFE" | |
| challenge: | |
| challenge-id: "b8ebcd40-1234-5678-3fb5-0e5d6a065904" | |
| challenge: "d57d919d11e6b882028f9221c9bf6f7c882028f9" | |
| response: "123456" | |
| compute-cr-challenge-request: | |
| description: Request with details to compute a CR challenge | |
| properties: | |
| user-id: | |
| type: string | |
| description: Unique identifier of the user whose token profile will be used do determine algorithm suite | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| example: | |
| token-sn: ASMT000ACAFACA | |
| compute-signature-challenge-request: | |
| description: Request with details to compute signature challenge | |
| required: | |
| - transaction-id | |
| - transaction-data | |
| properties: | |
| transaction-id: | |
| type: string | |
| description: Unique identifier of transaction being signed in applica. Mandatory when `challenge-mode` is `signature`. | |
| transaction-data: | |
| type: array | |
| description: Data from sensitive transaction that will be used as input for signature challenge. Mandatory when `challenge-mode` is `signature`. | |
| items: | |
| type: string | |
| user-id: | |
| type: string | |
| description: Unique identifier of the user whose token profile will be used do determine algorithm suite | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| example: | |
| transaction-id: 787781929 | |
| transaction-data: | |
| - AT61 1904 3002 3457 3201 | |
| - 12000.00 EUR | |
| token-sn: ASMT000ACAFACA | |
| generate-authentication-image-command: | |
| description: Instruction to generate an authentication image | |
| required: | |
| - callback-url | |
| properties: | |
| session-id: | |
| type: string | |
| description: Unique identifier of authentication session in calling application. | |
| user-id: | |
| type: string | |
| description: Unique identifier of the user whose token profile will be used do determine algorithm suite | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| image-options: | |
| $ref: "#/definitions/image-options" | |
| display: | |
| $ref: "#/definitions/display-metadata" | |
| callback-url: | |
| type: string | |
| format: uri | |
| example: | |
| session-id: 787781929 | |
| token-sn: ASMT000ACAFACA | |
| display: | |
| template: authentication | |
| callback-url: "https://online.bank.com/retail/authentication-callback/787781929" | |
| generate-signature-image-command: | |
| description: Instruction to generate a sugnature image | |
| required: | |
| - transaction-id | |
| - callback-url | |
| properties: | |
| transaction-id: | |
| type: string | |
| description: Unique identifier of transaction being signed in applica. | |
| transaction-data: | |
| type: array | |
| description: Field values from sensitive transaction that will be used as input for signature challenge. Mandatory when challenge is not present. | |
| items: | |
| type: string | |
| challenge: | |
| $ref: "#/definitions/challenge" | |
| user-id: | |
| type: string | |
| description: Unique identifier of the user whose token profile will be used do determine algorithm suite | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| image-options: | |
| $ref: "#/definitions/image-options" | |
| display: | |
| $ref: "#/definitions/display-metadata" | |
| callback-url: | |
| type: string | |
| format: uri | |
| example: | |
| transaction-id: 787781929 | |
| transaction-data: | |
| - AT61 1904 3002 3457 3201 | |
| - 12000.00 EUR | |
| token-sn: ASMT000ACAFACA | |
| image-options: | |
| x-size: 360 | |
| y-size: 360 | |
| display: | |
| transaction-kind: transfer | |
| labels: ["Destination account", "Amount"] | |
| callback-url: "https://online.bank.com/retail/signature-callback/787781929" | |
| initiate-authentication-push-message-command: | |
| description: Instruction to initiate push message authentication | |
| required: | |
| - callback-url | |
| properties: | |
| session-id: | |
| type: string | |
| description: Unique identifier of authentication session in calling application. | |
| user-id: | |
| type: string | |
| description: Unique identifier of the user whose token profile will be used do determine algorithm suite | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| image-options: | |
| $ref: "#/definitions/image-options" | |
| display: | |
| $ref: "#/definitions/display-metadata" | |
| callback-url: | |
| type: string | |
| format: uri | |
| example: | |
| session-id: 787781929 | |
| token-sn: ASMT000ACAFACA | |
| display: | |
| template: authentication | |
| callback-url: "https://online.bank.com/retail/authentication-callback/787781929" | |
| initiate-signature-push-message-command: | |
| description: Instruction to initiate signature push message | |
| required: | |
| - challenge-mode | |
| properties: | |
| transaction-id: | |
| type: string | |
| description: Unique identifier of transaction being signed in applica. | |
| transaction-data: | |
| type: array | |
| description: Field values from sensitive transaction that will be used as input for signature challenge. Mandatory when challenge is not present. | |
| items: | |
| type: string | |
| challenge: | |
| $ref: "#/definitions/challenge" | |
| user-id: | |
| type: string | |
| description: Unique identifier of the user whose token profile will be used do determine algorithm suite | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| display: | |
| $ref: "#/definitions/display-metadata" | |
| callback-url: | |
| type: string | |
| format: uri | |
| example: | |
| transaction-id: 787781929 | |
| transaction-data: | |
| - AT61 1904 3002 3457 3201 | |
| - 12000.00 EUR | |
| token-sn: ASMT000ACAFACA | |
| display: | |
| transaction-kind: transfer | |
| labels: ["Destination account", "Amount"] | |
| callback-url: "https://online.bank.com/retail/signature-callback/787781929" | |
| # RESPONSE MODELS | |
| verification-id: | |
| description: Unique identifier of OTC verification in progress. The MFA server will use this identifier to match validate OTC. | |
| type: string | |
| format: uuid | |
| example: "b8ebcd40-1234-5678-3fb5-0e5d6a065904" | |
| challenge: | |
| description: | | |
| Computed challenge. For signature mode it is 8 digits, 6 alphanumeric or 8 alphanumeric characters. For signature mode it will be 32 alphanumeric characters, 40 hex or 64 hex digits. | |
| type: string | |
| pattern: ^([0-9]{8,8}|[a-zA-Z0-9]{6,6}|[a-zA-Z0-9]{8,8}|[a-zA-Z0-9]{32,32}|[a-fA-F0-9]{40,40}|[a-fA-F0-9]{64,64})$ | |
| example: | |
| challenge-id: "b8ebcd40-1234-5678-3fb5-0e5d6a065904" | |
| challenge-mode: "signature" | |
| challenge: "d57d919d11e6b882028f9221c9bf6f7c882028f9" | |
| userinfo: | |
| description: A MFA profile of a user that has a list of assigned tokens | |
| properties: | |
| tokens: | |
| type: array | |
| items: | |
| $ref: "#/definitions/token" | |
| example: | |
| tokens: | |
| - token-type: hardware | |
| tokem-model: DP300 | |
| token-sn: VA010200000000921 | |
| - token-type: software | |
| tokem-model: LOGOS_OATH | |
| token-sn: ASMT000000FFE1 | |
| token: | |
| description: Token information | |
| properties: | |
| token-kind: | |
| type: string | |
| enum: [hardware, software] | |
| token-model: | |
| description: Unique name of the token model defined by manufacturer | |
| type: string | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| capabilities: | |
| description: Capabilities of MFA server | |
| properties: | |
| supported-capabilities: | |
| description: Signing methods available to user | |
| type: array | |
| items: | |
| type: string | |
| enum: | |
| - sms-otc | |
| - email-otc | |
| - signature-push-challenge | |
| - signature-image-challenge | |
| - cr-challenge-computation | |
| - signature-challenge-computation | |
| - authentication-push-otp | |
| - authentication-image-otp | |
| - multitenancy | |
| - token-enumeration | |
| - ocra | |
| - oath | |
| # CALLBACK NOTIFICATION MODELS | |
| oob-confirmation-notification: | |
| description: Notification with outcome of transaction confirmation | |
| required: | |
| - transaction-id | |
| - confirmation-result | |
| - response | |
| properties: | |
| transaction-id: | |
| type: string | |
| description: Unique identifier of transaction being signed in applica. | |
| confirmation-result: | |
| description: Outcome of the initiated confirmation. Once the user confirms the transaction, generated authentication code is sent to server for verification. If the server fails to verify the code it will be declared invalid. | |
| type: string | |
| enum: [rejected, verified, invalid, expired] | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| user-id: | |
| type: string | |
| description: Unique identifier of the user known to MFA server. Mandatory if `token-sn` is not present. | |
| response: | |
| $ref: "#/definitions/token-otp" | |
| example: | |
| transaction-id: 7167166716 | |
| confirmation-result: confirmed | |
| token-sn: "ASMT0000FFFE" | |
| response: "123456" | |
| oob-authentication-notification: | |
| description: Notification with details of outcome of authentication | |
| required: | |
| - session-id | |
| - authentication-result | |
| - otp | |
| properties: | |
| session-id: | |
| type: string | |
| description: Unique identifier of the authentication session supplied originaly by application | |
| authentication-result: | |
| description: Outcome of the initiated authentication. Once the user authenticates on mobile device, generated authentication code is sent to server for verification. If the server fails to verify the code it will be declared invalid. | |
| type: string | |
| enum: [rejected, verified, invalid, expired] | |
| token-sn: | |
| $ref: "#/definitions/token-sn" | |
| user-id: | |
| type: string | |
| description: Unique identifier of the user known to MFA server. Mandatory if `token-sn` is not present. | |
| otp: | |
| $ref: "#/definitions/token-otp" | |
| example: | |
| session-id: 7167166716 | |
| authentication-result: confirmed | |
| token-sn: "ASMT0000FFFE" | |
| otp: "123456" | |
| # DATA TYPE MODELS | |
| token-sn: | |
| type: string | |
| description: Token serial number. For OATH compliant tokens, format conform to OATH Token Identifier Specification. Mandatory if `token-sn` is not present. | |
| pattern: ^[A-Z]{2,2}[A-Z0-9]{2,2}[A-F0-9]{8,8}$ | |
| token-otp: | |
| type: string | |
| description: Digits generated by token. Format is 6 or 8 digits. | |
| pattern: ^([0-9]{6,6}|[0-9]{8,8})$ | |
| image-options: | |
| properties: | |
| x-size: | |
| description: Horizontal size of the image in pixels | |
| type: number | |
| format: int32 | |
| y-size: | |
| description: Vertical size of the image in pixels | |
| type: number | |
| format: int32 | |
| error-correction: | |
| description: Level of error correction information added to data when encoded as image | |
| type: number | |
| format: int32 | |
| margin-size: | |
| description: Widht in pixels of margin surrounding the information carying area of the image | |
| type: number | |
| format: int32 | |
| display-metadata: | |
| description: Metadata that will be used to present | |
| required: | |
| - template | |
| properties: | |
| template: | |
| description: Kind of confirmation | |
| type: string | |
| enum: | |
| - authentication | |
| - transfer | |
| - card-payment | |
| - consent | |
| - trusted-beneficiary | |
| title: | |
| description: Screen title | |
| type: string | |
| maxLength: 20 | |
| application: | |
| description: Application name | |
| type: string | |
| maxLength: 20 | |
| instruction: | |
| description: Text instructing user what to do | |
| type: string | |
| maxLength: 50 | |
| labels: | |
| type: array | |
| description: Display labels for transaction data. Must be in same order contain same number of items as transaction data. | |
| items: | |
| type: string | |
| confirm-action: | |
| description: Label of the action that confirms transaction | |
| type: string | |
| maxLength: 10 | |
| reject-action: | |
| description: Label of the action that rejects transaction | |
| type: string | |
| maxLength: 10 | |
| responses: | |
| validation-problem-response: | |
| description: Your request was not constructed properly. If the request was correctly formatted, response will contain validation errors for each invalid element of your request. For complete list of possible validation errors see the general [guidance on request validation](common-getstarted.html#error-handling). | |
| schema: | |
| $ref: '#/definitions/validation-problem' | |
| default-error-response: | |
| description: 'Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)' |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment