swagger: '2.0'
x-asee-visibility: public
info:
  description: Authorization API enables authorization of sensitive actions performed by customers or agents using 2nd factor authentication. Sensitive action authorizations can be explicitly requested by applications or they can be initiated by APIs during authorization checking. Support for 4 eyes verification and separation of duties will be added in future.
  title: Authorization API
  version: v1
host: bankapi.net
basePath: /v1/authorization
tags:
  - description: Working with one-time passwords
    name: OTP
consumes:
  - application/json
produces:
  - application/json
schemes:
  - https
  - http
paths:
  /otp/sms/send:
    post:
      summary: Generate and send SMS one-time password
      description: Generates one-time password and sends it to receipient specified in `user-id` or `phone-number`
      tags:
        - OTP
      x-asee-tags: []
      operationId: OTP_SendSMS
      parameters:
        - description: Command with details to send SMS OTP
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/send-sms-otp-command'
      responses:
        202:
          description: Accepted - SMS sent
          schema:
            $ref: '#/definitions/verification-id'
        440:
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            - [no-such-user]()
        default:
          $ref: '#/responses/default-error-response'

  /otp/sms/verify:
    post:
      operationId: OTP_VerifySMS
      summary: Verify SMS one-time password
      description: Verifies one-time password entered by user for verification in progress
      tags:
        - OTP
      x-asee-tags: []
      parameters:
        - description: Request with details to verify SMS OTP
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/verify-sms-otp-request'
      responses:
        204:
          description: No content - OTP is valid
        440:
          description: |
            Your request was well constructed but OTP was be verified. Consider the following possible problems and look into response for more details:

            - [bad-otp]()
            - [replayed-otp]()
            - [no-such-verification]()
        default:
          $ref: '#/responses/default-error-response'

  /otp/email/send:
    post:
      summary: Generate and send email with one-time password
      description: Generates one-time password and sends it to receipient specified in `user-id` or `email`
      tags:
        - OTP
      x-asee-tags: []
      operationId: OTP_SendEmail
      parameters:
        - description: Command with details to send OTP email
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/send-email-otp-command'
      responses:
        202:
          description: Accepted - Email sent
          schema:
            $ref: '#/definitions/verification-id'
        440:
          description: |
            Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details:

            - [no-such-user]()
        default:
          $ref: '#/responses/default-error-response'

  /otp/email/verify:
    post:
      operationId: OTP_VerifyEmail
      summary: Verify email one-time password
      description: Verifies one-time password entered by user for verification in progress
      tags:
        - OTP
      x-asee-tags: []
      parameters:
        - description: Request with details to verify email OTP
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/verify-email-otp-request'
      responses:
        204:
          description: No content - OTP is valid
        440:
          description: |
            Your request was well constructed but OTP coul not be verified. Consider the following possible problems and look into response for more details:

            - [bad-otp]()
            - [replayed-otp]()
            - [no-such-verification]()
        default:
          $ref: '#/responses/default-error-response'

  /otp/oath/verify:
    post:
      operationId: OTP_VerifyOATH
      summary: Verify OATH compliant one-time password
      description: Verifies TOTP or HOTP one-time password entered by user identified with `user-id`
      tags:
        - OTP
      x-asee-tags: []
      parameters:
        - description: Request with details to verify HOTP or TOTP
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/verify-oath-otp-request'
      responses:
        204:
          description: No content - OTP is valid
        440:
          description: |
            Your request was well constructed but OTP could not be verified. Consider the following possible problems and look into response for more details:

            - [bad-otp]()
            - [replayed-otp]()
            - [no-such-user]()
          schema:
            $ref: '#/definitions/business-problem'
        default:
          $ref: '#/responses/default-error-response'

  /ocra/challenge:
    post:
      operationId: OCRA_GenerateChallenge
      summary: Generate OCRA challenge
      description: Generates OCRA challenge based on optional data for signature provided by application or random seed
      tags:
        - OCRA
      x-asee-tags: []
      parameters:
        - description: Request with details to generate OCRA challenge
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/generate-ocra-challenge-request'
      responses:
        200:
          description: OK - OCRA challenge generated
          schema:
            $ref: '#/definitions/challenge'          
        440:
          description: |
            Your request was well constructed but OCRA challenge could not be generated. Consider the following possible problems and look into response for more details:

            - [no-such-user]()
          schema:
            $ref: '#/definitions/business-problem'
        default:
          $ref: '#/responses/default-error-response'
                    
  /ocra/verify:
    post:
      operationId: OCRA_VerifyResponse
      summary: Verify OCRA response
      description: Verifies OCRA response to previously generated challenge
      tags:
        - OCRA
      x-asee-tags: []
      parameters:
        - description: Request with details to verify OCRA response
          in: body
          name: cmd
          required: true
          schema:
            $ref: '#/definitions/verify-ocra-response-request'
      responses:
        204:
          description: No content - OCRA response is valid
        440:
          description: |
            Your request was well constructed but OCRA response could not be verified. Consider the following possible problems and look into response for more details:

            - [bad-response]()
            - [replayed-response]()
            - [no-such-challenge]()
          schema:
            $ref: '#/definitions/business-problem'
        default:
          $ref: '#/responses/default-error-response'

  '/evaluate-signatures':
    post:
      summary: 'Evaluates the existing signatures from supplied payload and calling context against signing rules defined.'
      description: 'Evaluates the existing signatures from supplied payload and calling context against signing rules defined.'
      tags:
        - Authorization
      operationId: Authorization_EvaluateSignatures
      parameters:
        - name: command
          description: "Request with details required for status of signing resource."
          in: body
          required: true
          schema:
            $ref: '#/definitions/evaluate-signatures-command'
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/evaluate-signatures-response'

  '/evaluate-user':
    post:
      summary: 'Evaluates the user for signing and accepts signature if user is allowed and/or valid.'
      description: 'Evaluates the user for signing and accepts signature if user is allowed and/or valid.'
      tags:
        - Authorization
      operationId: Authorization_EvaluateUser
      parameters:
        - name: command
          in: body
          required: true
          schema:
            $ref: '#/definitions/evaluate-user-command'
          description: "Request with details required for checking the signing rules and inserting a signature if user is allowed to sign the payload."
      responses:
        '200':
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/evaluate-user-response'

  '/authorization-levels':
    get:
      summary: "Provides authorization levels for a corporate"
      produces:
      - "application/json"
      tags:
        - Authorization
      parameters:
      - name: "identifier"
        in: "query"
        description: "Corporate ID (for corporate customers) or CIF (for detecting          \ joints)"
        required: true
        type: "string"
      - name: "bankId"
        in: "query"
        description: "Bank ID"
        required: true
        type: "string"
        enum:
        - "01"
        - "02"
      - name: "amount"
        in: "query"
        description: "Amount to authorize"
        required: false
        type: "number"
        minimum: 0
        format: "float32"
      - name: "currency"
        in: "query"
        description: "Currency code to filter on"
        required: false
        type: "string"
      - name: "accountID"
        in: "query"
        description: "AccountID to filter on"
        required: false
        type: "string"
      - name: "transactionType"
        in: "query"
        description: "Transaction Type"
        required: false
        type: "string"
        enum:
        - "N/A"
        - "SLF"
        - "TPF"
        - "PMT"
        - "RMT"
      - name: "authorizationType"
        in: "query"
        required: false
        type: "string"
        enum:
        - "PAYMENT"
        - "CANCELLATION"
        - "CONSENT"
        - "N/A"
      responses:
        200:
          description: "search results matching criteria"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/AuthorizationLevels"
        400:
          description: "bad input parameter"

parameters:
  include-param:
    description: List of fields to include in response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)
    in: query
    name: include
    type: array
    items:
      type: string
    collectionFormat: csv
    x-asee-common: true
  trim-param:
    description: List of fields to trim from response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)
    in: query
    name: trim
    type: array
    items:
      type: string
    collectionFormat: csv
    x-asee-common: true
  kinds-param:
    description: ''
    in: query
    name: kinds
    required: false
    collectionFormat: csv
    items:
      type: string
    type: array
  activity-permissions-type-param:
    description: ''
    in: query
    name: permissions-type
    required: false
    collectionFormat: csv
    enum:
      - execute
      - authorize
      - compensate
    items:
      type: string
    type: array
  conditionality-param:
    description: ''
    in: query
    name: conditionality
    required: false
    collectionFormat: csv
    enum:
      - conditional
      - unconditional
    items:
      type: string
    type: array
  activity-specification-kind-param:
    name: activity-specification-kind
    in: path
    required: true
    type: string
  activity-specification-id-param:
    name: activity-specification-id
    in: path
    required: true
    type: string
  activity-permission-type-param:  
    name: permission-type
    in: path
    required: true
    type: string
  resource-permissions-type-param:
    description: ''
    in: query
    name: permissions-type
    required: false
    collectionFormat: csv
    enum:
      - read
      - read-sensitive
      - add
      - modify
      - delete
      - share
      - authorize
    items:
      type: string
    type: array
  resource-id-param:
    name: resource-id
    in: path
    required: true
    type: string
  resource-kind-param:  
    name: resource-kind
    in: path
    required: true
    type: string
  resource-permission-type-param:
    description: ''
    in: path
    name: permission-type
    required: true
    enum:
      - read
      - read-sensitive
      - add
      - modify
      - delete
      - share
      - authorize
    type: string
    
definitions:
  business-problem:
    description: Details on specific problem that prevented processing after successfull validation
    type: object
    example:
      problem: document-locked
      message: Document you are trying to access is locked by another user
      details: User john.doe has locked the document
    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

  send-sms-otp-command:
    description: Command with details to send SMS OTP
    properties:
      action:
        type: string
        description: Optional service code of sensitive action that will be verified
      message:
        type: string
        description: Optional message to include in SMS sent to user
      phone-number:
        type: string
        format: phone
        description: Phone number that will receive OTP
      user-id:
        type: string
        description: Optional identifier of user who will receive SMS on preferred mobile phone number.
    example:
      action: auth-01
      message: authentication
      phone-number: "+38165222333"
      user-id: test.user

  send-email-otp-command:
    description: Command with details to send email OTP
    properties:
      action:
        type: string
        description: Optional service code of sensitive action that will be verified
      message:
        type: string
        description: Optional message to include in SMS sent to user
      email:
        type: string
        format: email
        description: Email that will receive OTP
      user-id:
        type: string
        description: Optional identifier of user who will receive SMS on preferred mobile phone number.
    example:
      action: auth-01
      message: authentication
      email: "test.user@mybank.com"
      user-id: test.user

  verification-id:
    description: Identifies SMS OTP verification in progress
    type: string
    example: "2112"

  verify-sms-otp-request:
    description: Request with details to verify SMS OTP
    properties:
      verification-id:
        description: Identifies SMS OTP verification in progress
        type: string
      otp:
        type: string
        description: Digits sent via SMS
    example:
      verification-id: "21123456"
      otp: "1234"

  verify-email-otp-request:
    description: Request with details to verify Email OTP
    properties:
      verification-id:
        description: Identifies SMS OTP verification in progress
        type: string
      otp:
        type: string
        description: Digits sent via Email
    example:
      verification-id: "21123456"
      otp: "123456"

  verify-oath-otp-request:
    description: Request with details to verify HOTP or TOTP
    required:
      - user-id
      - otp
    properties:
      user-id:
        type: string
        description: For existing user (customer or agent)
      otp:
        type: string
        description: Digits generated by HOTP or TOTP
    example:
      user-id: "test.user"
      otp: "123456"

  generate-ocra-challenge-request:
    description: Request with details to generate OCRA challenge
    properties:
      challenge-mode:
        type: string
        description: One of the supported OCRA modes for challenge
        enum: [signature, random]
      signature-data:
        type: string
        description: Data to be signed provided by application as a reference to transaction. Used only with signature mode of challenge.
      user-id:
        type: string
        description: Identifier of user whose secret will be used to generate challenge
    example:
      challenge-mode: signature
      signature-data: 1601231231231231|12000.00RSD
      user-id: test.user
  
  challenge:
    description: Challenge data generated
    properties:
      challenge-id:
        description: Identifies challenge in progress for which response will be verified 
        type: string
      challenge-code:
        type: string
        description: Digits generated as challenge code
    example:
      challenge-id: "21123422"
      challenge-code: "78778718"
  
  verify-ocra-response-request:
    description: Request with details to verify OCRA response
    properties:
      challenge-id:
        description: Identifies challenge in progress for which response is verified 
        type: string
      response-code:
        type: string
        description: Digits entered as response
    example:
      challenge-id: "21123456"
      response-code: "123456"
      
  evaluate-command:
    type: object
    required:
      - resource-id
    properties:
      resource-kind:
        type: string
        description: "Resource type identifier used for rules setting"
      resource-id:
        type: string
        description: "Resource identifier. Exact resource being evaluated for signature identificator"
      payload:
        type: string
        description: "Serialized payload of the evaluation request. Digest is calculated for that payload which represents unique resource being evaluated. If anything is changed on payload during signing process, existing signatures associated with digest will be lost and not valid."
      calling-context:
        type: string
        description: "Serialized calling context represents call specific data."
    example:
      resource-id: "abcde-12345-abcde"
      resource-kind: "sepa-credit-transfer"
      payload: "{\"endToEndIdentification\":\"BIPI-123456789RI-123456789\",\"debtorAccount\":{\"iban\":\"AT10000113860171232\"},\"instructedAmount\":{\"amount\":\"55.00\",\"currency\":\"EUR\"},\"creditorAccount\":{\"iban\":\"AT10000113860171232\"},\"creditorName\":\"Test PSD2 Interface\",\"purposeCode\":\"nekiCode\",\"remittanceInformationUnstructured\":\"Initiating payment via Postman\",\"requestedExecutionTime\":\"2018-12-30T10:02:29.073Z\"}"
  
  evaluate-user-command:
    type: object
    allOf:
    - $ref: '#/definitions/evaluate-command'
  
  evaluate-signatures-command:
    type: object
    allOf:
    - $ref: '#/definitions/evaluate-command'
  
  evaluate-response:
    type: object
    properties:
      success:
        type: boolean
        description: Indicates wether signing rules are furfilled or not.

  evaluate-user-response:
    type: object
    allOf:
    - $ref: '#/definitions/evaluate-response'
    properties:
      reason:
        type: string
        description: Explanation of status returned. If operation resulted in success, signature is accepted and reason is set to signatures-accepted, otherwise success is set to false and user is either already signed a resosurce or user cannot sign the resource.
        enum: [signature-accepted,user-already-signed,user-cannot-sign]
  
  evaluate-signatures-response:
    type: object
    allOf:
    - $ref: '#/definitions/evaluate-response'
    properties:
      reason:
        type: string
        description: Explanation of status returned
        enum: [furfilled,additional-signatures-required]
      signatures:
        type: array
        items:
          $ref: '#/definitions/signatures'
        description: Required and existing signatures per entity resource
    example:
      success: false
      reason: "additional-signatures-required"
      signatures:
      - entity: "sg-01"
        required: 2
        existing: 1
      - entity: "user-02"
        required: 1
        existing: 0
    
  signatures:
    type: object
    properties:
      entity:
        type: string
        description: Entity type level being used for evaluation. UserName, user id, customer, customer group, customer special groups used for signing
      required:
        type: integer
        description: Number of required signatures of specified entity. Usualy this value, along with entity being used is set in signing model definition.
      existing:
        type: integer
        description: Number of existing valid signatures.
    example:
        entity: "sg-01"
        required: 2
        existing: 1
  
  AuthorizationLevels:
    type: "object"
    properties:
      searchCriteria:
        $ref: "#/definitions/AuthorizationLevels_searchCriteria"
      Authorizations:
        $ref: "#/definitions/AuthorizationLevels_Authorizations"
    example:
      Authorizations:
        EnforceHierarchy: false
        type: "PAYMENT"
        levels:
        - level: 1
          authorizationCount: 1
          currency: "EUR"
          account: "1234567891213123"
          users:
          - name: "JONJ001"
          - name: "JONJ001"
        - level: 1
          authorizationCount: 1
          currency: "EUR"
          account: "1234567891213123"
          users:
          - name: "JONJ001"
          - name: "JONJ001"
      searchCriteria:
        transactionType: "PMT"
        identifier: "CORP001"
        accountID: "1234567891213123"
        amount: 15000.22999999999956344254314899444580078125
        bankID: "1"
        ccy: "EUR"
        authorizationType: "N/A"
  AuthorizationLevels_searchCriteria:
    properties:
      identifier:
        type: "string"
        example: "CORP001"
      amount:
        type: "number"
        format: "float32"
        example: 15000.22999999999956344254314899444580078125
      ccy:
        type: "string"
        example: "EUR"
      accountID:
        type: "string"
        example: "1234567891213123"
      bankID:
        type: "string"
        example: "1"
      transactionType:
        type: "string"
        example: "PMT"
      authorizationType:
        type: "string"
        example: "N/A"
    example:
      transactionType: "PMT"
      identifier: "CORP001"
      accountID: "1234567891213123"
      amount: 15000.22999999999956344254314899444580078125
      bankID: "1"
      ccy: "EUR"
      authorizationType: "N/A"
  AuthorizationLevels_Authorizations_users:
    properties:
      name:
        type: "string"
        example: "JONJ001"
    example:
      name: "JONJ001"
  AuthorizationLevels_Authorizations_levels:
    properties:
      level:
        type: "integer"
        example: 1
      authorizationCount:
        type: "integer"
        example: 1
      currency:
        type: "string"
        example: "EUR"
      account:
        type: "string"
        example: "1234567891213123"
      users:
        type: "array"
        items:
          $ref: "#/definitions/AuthorizationLevels_Authorizations_users"
    example:
      level: 1
      authorizationCount: 1
      currency: "EUR"
      account: "1234567891213123"
      users:
      - name: "JONJ001"
      - name: "JONJ001"
  AuthorizationLevels_Authorizations:
    properties:
      type:
        type: "string"
        example: "PAYMENT"
      EnforceHierarchy:
        type: "boolean"
        example: false
      levels:
        type: "array"
        items:
          $ref: "#/definitions/AuthorizationLevels_Authorizations_levels"
    example:
      EnforceHierarchy: false
      type: "PAYMENT"
      levels:
      - level: 1
        authorizationCount: 1
        currency: "EUR"
        account: "1234567891213123"
        users:
        - name: "JONJ001"
        - name: "JONJ001"
      - level: 1
        authorizationCount: 1
        currency: "EUR"
        account: "1234567891213123"
        users:
        - name: "JONJ001"
        - name: "JONJ001"
        
responses:
  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)'