openapi: 3.0.3
info:
  title: COREN External Verification API
  version: 1.0.0
  description: |
    Authorized consumer verification APIs. Authenticate with X-Api-Key and HMAC-SHA256.
    Sandbox base path is /api/sandbox/v1.
servers:
  - url: /api/v1
    description: Production
  - url: /api/sandbox/v1
    description: Sandbox
paths:
  /verify/practitioner:
    post:
      summary: Verify a practitioner
      security: []
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Signature'
        - $ref: '#/components/parameters/Timestamp'
        - $ref: '#/components/parameters/Nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationRequest'
      responses:
        '200':
          description: Practitioner found
        '401':
          description: Authentication failed
        '403':
          description: Forbidden
        '404':
          description: Not found
        '429':
          description: Rate limited
  /verify/firm:
    post:
      summary: Verify a firm
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Signature'
        - $ref: '#/components/parameters/Timestamp'
        - $ref: '#/components/parameters/Nonce'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationRequest'
      responses:
        '200':
          description: Firm found
        '401':
          description: Authentication failed
        '404':
          description: Not found
components:
  parameters:
    ApiKey:
      name: X-Api-Key
      in: header
      required: true
      schema:
        type: string
    Signature:
      name: X-Api-Signature
      in: header
      required: true
      schema:
        type: string
    Timestamp:
      name: X-Api-Timestamp
      in: header
      required: true
      schema:
        type: string
    Nonce:
      name: X-Api-Nonce
      in: header
      required: true
      schema:
        type: string
  schemas:
    VerificationRequest:
      type: object
      required: [reference]
      properties:
        reference:
          type: string
          description: Practitioner or firm license number
          example: R12345
    VerificationSuccess:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        data:
          type: object
        meta:
          type: object
          properties:
            request_id:
              type: string
            timestamp:
              type: string
    VerificationError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        error_code:
          type: string
          example: not_found
        meta:
          type: object
