> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spoofsense.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a verification session

> Called from your backend with the secret key. Mints a single-use `sst_` client token — returned exactly once, only its hash is stored. Products and thresholds are fixed here, server-side; the client can never change them. Fails fast with 402 if your balance is empty, so you never hand out a doomed token.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/verification_sessions
openapi: 3.1.0
info:
  title: SpoofSense API
  version: '1.0'
  description: >-
    Face liveness and deepfake detection. All errors use the envelope `{"error":
    {"code", "message"}}`. Input errors (4xx) are never charged.
servers:
  - url: https://api.spoofsense.ai
security:
  - secretKey: []
tags:
  - name: Detection
    description: >-
      Stateless checks on an image you already have. Authenticate with your
      secret key.
  - name: Verification sessions
    description: >-
      The secure capture flow used by the SDKs and hosted page. Server-side
      calls use the secret key; client-side calls use the session's sst_ token.
  - name: Service
paths:
  /v1/verification_sessions:
    post:
      tags:
        - Verification sessions
      summary: Create a verification session
      description: >-
        Called from your backend with the secret key. Mints a single-use `sst_`
        client token — returned exactly once, only its hash is stored. Products
        and thresholds are fixed here, server-side; the client can never change
        them. Fails fast with 402 if your balance is empty, so you never hand
        out a doomed token.
      operationId: createVerificationSession
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                products:
                  type: array
                  items:
                    type: string
                    enum:
                      - face_liveness
                      - deepfake
                  description: >-
                    Which checks to run on the capture. Defaults to both.
                    Liveness only = 1 credit, deepfake only = 2, both = 3.
                thresholds:
                  type: object
                  description: >-
                    Per-product threshold override, e.g. {"face_liveness": 0.6}.
                    Values in [0,1]. Defaults to your org settings.
                  additionalProperties:
                    type: number
                    minimum: 0
                    maximum: 1
                ttl_seconds:
                  type: integer
                  default: 900
                  minimum: 60
                  maximum: 3600
                  description: How long the session stays usable. Clamped to 60–3600.
                reference_id:
                  type: string
                  maxLength: 256
                  description: Your own user/transaction id, echoed back on reads.
                metadata:
                  type: object
                  description: Arbitrary JSON, at most 4096 bytes, echoed back on reads.
            example:
              products:
                - face_liveness
                - deepfake
              reference_id: user_123
      responses:
        '200':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationSessionCreated'
              example:
                object: verification_session
                id: vs_1f2e3d4c5b6a79880917263544332211
                status: created
                client_token: sst_Zk9qX1J2c3Q0dTV2Nnc3eDh5OXow
                nonce: 8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f
                products:
                  - face_liveness
                  - deepfake
                reference_id: user_123
                expires_at: '2026-01-01T12:15:00+00:00'
                created_at: '2026-01-01T12:00:00+00:00'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
components:
  schemas:
    VerificationSessionCreated:
      type: object
      properties:
        object:
          type: string
          enum:
            - verification_session
        id:
          type: string
          description: vs_… id. Keep server-side to fetch the result later.
        status:
          type: string
          enum:
            - created
        client_token:
          type: string
          description: >-
            sst_… token for the SDK. Returned exactly once — only its hash is
            stored.
        nonce:
          type: string
          description: >-
            Bound into the submit payload; also available to the SDK via
            session_info.
        products:
          type: array
          items:
            type: string
        reference_id:
          type:
            - string
            - 'null'
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    BadRequest:
      description: BAD_REQUEST · INVALID_THRESHOLD · NONCE_MISMATCH
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: BAD_REQUEST
              message: Provide 'data' (base64) or 'image_url'
    Unauthorized:
      description: UNAUTHORIZED — missing, invalid, or revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Missing, invalid, or revoked API key
    InsufficientCredits:
      description: INSUFFICIENT_CREDITS — top up in the console
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INSUFFICIENT_CREDITS
              message: Insufficient credits
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: >-
        Your secret key (sk_live_…), server-side only. Also accepted as an
        `x-api-key` header.

````