AffixIO Otp API

openapi: 3.2.0
info:
  title: AffixIO Verification Otp API
  version: 1.8.0
  description: Public /v1 and /api surface of the AffixIO verification API (ML-DSA-65 signed yes/no results, Noir/Barretenberg circuits, Merkle audit, spent registry, gates, Agent Trust). Generated from the live MCP endpoint catalogue and the Postman collection at https://api.affix-io.com/openapi.postman.json. Account, key, OAuth, Hub and webhook administration are intentionally omitted. A successful verify spends the proof digest; presenting it again returns 409 double_spend_detected. Send Idempotency-Key on prove/verify to retry safely.
  contact:
    name: AffixIO
    url: https://www.affix-io.com/contact/
servers:
- url: https://api.affix-io.com
tags:
- name: Otp
paths:
  /v1/otp/issue:
    post:
      operationId: affix_otp_issue
      summary: Issue a six-digit door code
      description: Issue a short-lived six-digit code bound to a proof, for staffed doors. The response includes code and expires_at.
      security:
      - ApiKey: []
      - Bearer: []
      responses:
        '201':
          description: Carrier issued.
        '400':
          description: proof_required (no proof_digest or proof_ref), unknown_proof, or invalid_request.
        '401':
          description: API key missing or not accepted.
        '403':
          description: 'proof_not_owned: the proof was created with a different API key.'
        '409':
          description: 'already_used: the proof has already been consumed.'
        '429':
          description: Rate limited; see Retry-After.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierIssueRequest'
            example:
              proof_ref: pf_00000000-0000-0000-0000-000000000000
              gate_id: main-door
              label: door-1
              ttl_seconds: 60
      tags:
      - Otp
  /v1/otp/verify:
    post:
      operationId: affix_otp_verify
      summary: Verify a door code
      description: Verify and consume a six-digit door code. A code works once. Returns 409 used if its proof has already been spent.
      security:
      - ApiKey: []
      - Bearer: []
      responses:
        '200':
          description: Valid. allow is true.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierVerifyResponse'
        '400':
          description: Not valid (expired, not_found, invalid).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierVerifyResponse'
        '409':
          description: 'used: the carrier or its bound proof has already been spent.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierVerifyResponse'
        '401':
          description: API key missing or not accepted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                otp:
                  type: string
                  pattern: ^[0-9]{6}$
                proof_digest:
                  type: string
                  description: Optional. When given, the code must belong to this proof.
            example:
              otp: '123456'
      tags:
      - Otp
components:
  schemas:
    CarrierIssueRequest:
      type: object
      description: Every presentment carrier must be bound to a proof you created with this API key. Send proof_digest (64 hex) or proof_ref (the proof_id from prove). Empty, unknown, someone else's or already spent proofs are refused.
      properties:
        proof_digest:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: proof_digest returned by prove.
        proof_ref:
          type: string
          description: proof_id returned by prove (e.g. pf_...). Used when proof_digest is omitted.
        circuit_id:
          type: string
        gate_id:
          type: string
          maxLength: 64
        label:
          type: string
          maxLength: 64
          description: Your label. Not shown on the public status page.
        ttl_seconds:
          type: integer
          minimum: 1
          maximum: 2592000
        meta:
          type: object
          additionalProperties: true
    CarrierVerifyResponse:
      type: object
      properties:
        allow:
          type: boolean
        reason_code:
          type: string
          description: VALID when allowed. Otherwise e.g. used, expired, not_found.
        spent:
          type: boolean
          description: True once the bound proof has been consumed at a gate or the carrier was consumed.
        carrier:
          type: object
          additionalProperties: true
        policy_version:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
    Bearer:
      type: http
      scheme: bearer