{
  "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": "US production environment"
    },
    {
      "url": "https://api.eu.transmitsecurity.io/verify",
      "description": "EU production environment"
    },
    {
      "url": "https://api.ca.transmitsecurity.io/verify",
      "description": "CA production environment"
    },
    {
      "url": "https://api.au.transmitsecurity.io/verify",
      "description": "AU production environment"
    },
    {
      "url": "https://api.gasne1-ts01.transmitsecurity.io/verify",
      "description": "JP production environment"
    }
  ],
  "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"
        ]
      }
    }
  }
}