DIA OTI Swagger definition draft

oti-openapi.yaml

openapi: 3.0.0
info:
  description: API Spec for OTI
  termsOfService: /tos
  title: OTI API
  version: 0.0.1
components:
  securitySchemes:
      api_key:
        type: http
        scheme: bearer
      session_token:
        type: apiKey
        in: header
        name: OTI-Auth
paths:
  /start-session:
    post:
      description: Verifies the Passport information and creates a session token
      summary: Verify the passport information and start a session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                document_source:
                  description: Source of the document
                  type: string
                document_number:
                  description: The users Passport number
                  type: string
                document_given_names:
                  description: The users first name
                  type: string
                document_surname:
                  description: The users last name
                  type: string
                document_date_of_expiry:
                  description: The expiry date of the document
                  type: string
                  format: date
                document_date_of_birth:
                  description: The users date of birth
                  type: string
                  format: date
                document_place_of_birth:
                  description: The users place of birth
                  type: string
                document_gender:
                  description: The users gender
                  type: string
                contact_email_address:
                  description: The users email
                  type: string
                  format: email
                contact_mobile_number:
                  description: The users phone number
                  type: string
                  format: phone-number
              required:
                - document_source
                - document_number
                - document_given_names
                - document_surname
                - document_date_of_expiry
                - document_date_of_birth
                - contact_email_address
                - contact_mobile_number
      security: 
      - api_key: []
      responses:
        '200':
          description: Passport information verified and session started
          content:
            application/json:
              schema:
                properties:
                  session_token:
                    description: The session token to use throughout the process
                    type: string
        '400':
          description: Missing parameter, wrong passport information
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: Message with missing value needed
                    type: string
        '401':
          description: Missing credentials, credentials wrong
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Unauthorised message
                    type: string
        '500':
          description: An error occurred
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: The error that occurred
                    type: string
      tags:
      - Start Session
  /provide-liveness-challenges:
    post:
      description: Get the three challenges for the current on-boarding attempt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                device_info:
                  type: object
                  description: Optional description of the users device
                  properties:
                    latitude:
                      description: Latitude of device
                      type: integer
                    longitude:
                      description: Longitude of device
                      type: integer
                    make:
                      description: Make of device
                      type: string
                    model:
                      description: Model of device
                      type: string
                    name:
                      description: Device Name
                      type: string
                    version:
                      description: Device OS version
                      type: string
                face:
                  description: Base64 encoded profile image of user
                  type: string
                  format: base64
              required:
                - face
                - device_info
      security: 
      - api_key: []
      - session_token: []
      responses:
        '200':
          description: Successfully enrolled and got challenges
          content:
            application/json:
              schema:
                type: object
                description: An object containing the challenges, current attempt and max attempts
                properties:
                  attempt:
                    description: >-
                      Current attempt number (added to returned challenges object
                      by this service)
                    type: integer
                  maxAttempts:
                    description: >-
                      Maximum allowed attempts (added to returned challenges
                      object by this service)
                    type: integer
                  challenges:
                    type: array
                    description: An array of challenges
                    items:
                      properties:
                        challengeType:
                          type: string
                          description: The challenge
                          enum:
                          - SHAKE
                          - BLINK
                          - NOD
        '400':
          description: Missing parameter
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: Message with missing value needed
                    type: string
                type: object
        '401':
          description: Missing credentials, credentials wrong
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Unauthorised message
                    type: string
        '429':
          description: User has used all their available attempts
          content:
            application/json:
              schema:
                properties:
                  attempt:
                    description: The attempt number the user is on
                    type: integer
                  error:
                    description: An error message explaining what happened
                    type: string
                  maxAttempts:
                    description: The configured max attempt number
                    type: integer
                type: object
        '500':
          description: An error occurred
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: The error that occurred
                    type: string
                type: object
      summary: Get all three challenges for current attempt and enrol user if needed
      tags:
        - Challenges
  /evaluation:
    get:
      description: Evaluate the tests and tell IVS the results
      security: 
      - api_key: []
      - session_token: []
      responses:
        '200':
          description: Evaluation has completed
          content:
            json/application:
              schema:
                type: object
                properties:
                  document_source:
                    description: The source of the document
                    type: string
                  oti_id:
                    description: The OTI Id
                    type: string
                    format: uuid
                  document_given_names:
                    type: object
                    properties:
                      value:
                        description: The given name on the document
                        type: string
                      status:
                        type: string
                  document_surname:
                    type: object
                    properties:
                      value:
                        description: The surname on the document
                        type: string
                      status:
                        type: string
                  document_date_of_expiry:
                    type: object
                    properties:
                      value:
                        description: The documents expiry date
                        type: string
                        format: date
                      status:
                        type: string
                  document_date_of_birth:
                    type: object
                    properties:
                      value:
                        description: The date of birth on the document
                        type: string
                        format: date
                      status:
                        type: string
                  document_place_of_birth:
                    type: object
                    properties:
                      value:
                        description: The place of birth on the document
                        type: string
                      status:
                        type: string
                  document_gender:
                    type: object
                    properties:
                      value:
                        description: The gender on the document
                        type: string
                      status:
                        type: string
                  document_photo_fr:
                    type: object
                    properties:
                      claimed_photo:
                        description: The selfie photo submitted
                        type: string
                        format: base64
                      status:
                        description: Result of matching the passport photo and the selfie photo
                        type: string
                        enum:
                          - match
                          - no match
                  liveness_result:
                    description: The results of the evaluation
                    type: object
                    properties:
                      shake_result:
                        description: The result of the shake liveness test
                        type: string
                        enum:
                          - pass
                          - fail
                      nod_result:
                        description: The result of the nod liveness test
                        type: string
                        enum:
                          - pass
                          - fail
                      blink_result:
                        description: The result of the blink liveness test
                        type: string
                        enum:
                          - pass
                          - fail
        '202':
          description: 'Tests are still evaluating, please check again later'
          content:
            application/json:
              schema:
                properties:
                  items:
                    description: The challenges with the processing status
                    items:
                      properties:
                        id:
                          description: ID of this challenge
                          type: string
                        processing_status:
                          description: >-
                            Processing status of the challenge on the Daon On
                            Boarding server
                          type: string
                      type: object
                    type: array
                type: object
        '401':
          description: Credentials missing, credentials wrong
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Unauthorised message
                    type: string
        '500':
          description: Something went wrong during the evaluation
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: The error that occurred
                    type: string
                type: object
      summary: Evaluate the Liveness and Passport tests.
      tags:
        - Evaluation
  /upload-video:
    post:
      description: Upload the video for a challenge
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                json:
                  type: object
                  description: object containing type
                  properties:
                    type:
                      description: the type of challenge
                      type: string
                      enum:
                        - NOD
                        - BLINK
                        - SHAKE
                video:
                  type: string
                  description: Video of challenge
                  format: binary
              required:
                - json
                - video
      security:
      - api_key: []
      - session_token: []
      responses:
        '200':
          description: Video uploaded successfully
        '400':
          description: Missing parameter
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: Message with missing value needed
                    type: string
                type: object
        '401':
          description: Missing credentials, credentials wrong
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    description: Unauthorised message
                    type: string
        '500':
          description: An error occurred
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: The error that occurred
                    type: string
                type: object
      summary: Upload the video challenges
      tags:
        - Video