openapi: 3.0.3
info:
  title: Acuant ACAS (Cloud Service) Authentication Liveness API
  description: Acuant Cloud Authentication Service (ACAS) provides authentication token management for initializing and authorizing SDK and API sessions. Supports Basic Auth (Base64) credential exchange and bearer token issuance for use with other Acuant APIs. Regional endpoints available for USA, EU, AUS, and preview environments.
  version: '1.0'
  contact:
    name: Acuant Support
    url: https://support.acuant.com
  x-api-id: acuant:acas
servers:
- url: https://us.acas.acuant.net
  description: USA Production
- url: https://eu.acas.acuant.net
  description: EU Production
- url: https://aus.acas.acuant.net
  description: AUS Production
- url: https://preview.acas.acuant.net
  description: Preview / Sandbox
security:
- 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:
  schemas:
    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
    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.
    Error:
      type: object
      properties:
        Code:
          type: integer
          description: Error code
        Message:
          type: string
          description: Error description
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication. Credentials encoded as Base64("username:password") in the Authorization header.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT bearer token obtained from the /api/v1/token endpoint.