openapi: 3.0.0
paths:
  /api/v1/face-auth:
    post:
      operationId: createFaceAuthSession
      summary: Create session
      description: >-
        Creates a new face authentication session that will provide a secure
        context to the process. It returns a device session ID that will be used
        when initiating the authentication process from the client side. This
        should be called from the backend.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFaceAuthSessionRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFaceAuthSessionResponse'
      security:
        - verify_access_token: []
  /api/v1/face-auth/{sid}/result:
    get:
      operationId: getAuthSessionResult
      summary: Get result
      description: >-
        Retrieves the result of the face authentication session, which indicates
        if the user-provided selfie matches the reference image. This should be
        called from the backend.
      parameters:
        - name: dsid
          required: true
          in: path
          schema: {}
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceAuthSessionResultResponse'
      security:
        - verify_access_token: []
info:
  title: Face Authentication
  description: >-
    Manage the face authentication sessions that are used to securely verify the
    identity of your customers by biometrically matching a selfie to a known
    image of the user.
  version: ''
  contact: {}
tags: []
servers:
  - url: https://api.sbx.transmitsecurity.io/verify
    description: Sandbox environment
  - url: https://api.transmitsecurity.io/verify
    description: Production environment (US)
  - url: https://api.eu.transmitsecurity.io/verify
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/verify
    description: Production environment (CA)
  - url: https://api.au.transmitsecurity.io/verify
    description: Production environment (AU)
components:
  securitySchemes:
    verify_access_token:
      scheme: bearer
      bearerFormat: jwt
      type: http
      description: >-
        An access token generated by the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken), which must
        target the following resource: `https://verify.identity.security` (in
        the future we’ll block access to tokens without this resource).
  schemas:
    RawImage:
      type: object
      description: Contains the reference image itself
      properties:
        type:
          type: string
          enum:
            - raw
        content:
          type: string
          description: >-
            The content of the image, as a base64 string. To get optimal
            results, the image resolution should be HD to FHD ( ~1900 X 1000).
        format:
          type: string
          description: The data format of the image. Currently, only jpg is supported
      required:
        - type
        - content
        - format
    CreateFaceAuthSessionRequest:
      type: object
      properties:
        reference:
          oneOf:
            - $ref: '#/components/schemas/RawImage'
        use_case:
          type: string
          description: >-
            Use case for the face authentication flow. Will be used in the
            future for per use case configurations.
          enum:
            - login
            - credentials-recovery
            - step-up
          default: login
      required:
        - reference
    CreateFaceAuthSessionResponse:
      type: object
      properties:
        session_id:
          type: string
          description: Identifier for the created session
        device_session_id:
          type: string
          description: >-
            Identifier for the created device session (also referred to as
            DSID). This must be used by the client when initiating the face
            authentication session in order to bind the device to the session.
      required:
        - session_id
        - device_session_id
    FaceAuthSessionResultResponse:
      type: object
      properties:
        status:
          type: string
          description: The status of the session
          enum:
            - pending
            - capturing
            - processing
            - complete
        recommendation:
          type: string
          description: >-
            The recommendation for the session. This is based on our level of
            confidence that the user-provided image matches the reference image
          enum:
            - ALLOW
            - CHALLENGE
            - DENY
      required:
        - status
