openapi: 3.0.3
info:
  title: Acuant Passive Liveness API
  description: >-
    Liveness detection API that evaluates a selfie image for presentation
    attacks including printed photos, masks, deepfakes, and face-swap attacks.
    Returns a LivenessAssessment (Live, NotLive, PoorQuality, Error) and a
    confidence score. ISO/IEC 30107-3 compliant with iBeta PAD Level 1 and
    Level 2 certification. No active liveness challenges required — a single
    selfie image is sufficient.
  version: '1.0'
  contact:
    name: Acuant Support
    url: https://support.acuant.com
  x-api-id: acuant:passive-liveness
servers:
  - url: https://us.passlive.acuant.net
    description: USA Production
  - url: https://eu.passlive.acuant.net
    description: EU Production
  - url: https://aus.passlive.acuant.net
    description: AUS Production
  - url: https://preview.passlive.acuant.net
    description: Preview / Sandbox
security:
  - BearerAuth: []
  - BasicAuth: []
tags:
  - name: Liveness
    description: Passive liveness detection operations
paths:
  /api/v1/liveness:
    post:
      operationId: checkLiveness
      summary: Evaluate image for liveness
      description: >-
        Submits a selfie image for passive liveness detection. The API
        analyzes the image for presentation attack indicators and returns
        an assessment of whether a live person is depicted. Detects printed
        photos, masks, screen replays, deepfakes, and face-swap attacks.
      tags:
        - Liveness
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LivenessRequest'
            example:
              SubscriptionId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              Image: "<base64-encoded-selfie-image>"
      responses:
        '200':
          description: Liveness detection result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LivenessResult'
              example:
                LivenessAssessment: "Live"
                Score: 92.3
                TransactionId: "txn-b2c3d4e5"
        '400':
          description: Invalid request or poor image quality
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Inactive subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token obtained from the ACAS (Cloud Authentication Service).
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication with Acuant credentials.

  schemas:
    Error:
      type: object
      properties:
        Code:
          type: integer
          description: Error code
        Message:
          type: string
          description: Error description

    LivenessRequest:
      type: object
      required:
        - SubscriptionId
        - Image
      properties:
        SubscriptionId:
          type: string
          format: uuid
          description: Acuant subscription identifier
        Image:
          type: string
          format: byte
          description: >-
            Base64-encoded selfie image. Recommended minimum resolution
            for reliable liveness detection.

    LivenessResult:
      type: object
      properties:
        LivenessAssessment:
          type: string
          enum:
            - Live
            - NotLive
            - PoorQuality
            - Error
          description: >-
            Assessment outcome.
            - Live: The image depicts a live person.
            - NotLive: A presentation attack was detected.
            - PoorQuality: Image quality is insufficient for assessment.
            - Error: Processing error occurred.
        Score:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: >-
            Confidence score (0-100) for the liveness assessment.
            Higher values indicate greater confidence in the Live assessment.
        TransactionId:
          type: string
          description: Unique identifier for this liveness check transaction
        Error:
          type: string
          nullable: true
          description: Error description if LivenessAssessment is Error
        ErrorCode:
          type: integer
          nullable: true
          description: Numeric error code if processing failed