naftiko: 1.0.0-alpha2
info:
  label: Vonage User Authentication
  description: Phone-based authentication workflow combining Vonage Verify API and Numbers API. Enables two-factor authentication,
    user onboarding verification, and phone number provisioning. Used by identity teams, onboarding flows, and fraud prevention
    systems.
  tags:
  - Authentication
  - Communication
  - Identity
  - Number Management
  - Security
  - Two-Factor Authentication
  - Vonage
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    VONAGE_API_KEY: VONAGE_API_KEY
    VONAGE_API_SECRET: VONAGE_API_SECRET
capability:
  consumes:
  - type: http
    namespace: vonage-verify
    baseUri: https://api.nexmo.com
    description: Vonage Verify API for phone verification and 2FA.
    authentication:
      type: apikey
      key: api_key
      value: '{{VONAGE_API_KEY}}'
      placement: body
    resources:
    - name: verify
      path: /verify/json
      description: Request phone number verification.
      operations:
      - name: request-verification
        method: POST
        description: Start a phone verification workflow.
        inputParameters:
        - name: number
          in: body
          type: string
          required: true
          description: Phone number to verify (E.164 format).
        - name: brand
          in: body
          type: string
          required: true
          description: Brand name shown in the verification message.
        - name: code_length
          in: body
          type: integer
          required: false
          description: Length of verification code (4 or 6).
        - name: workflow_id
          in: body
          type: integer
          required: false
          description: Workflow ID selecting SMS/TTS sequence.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: verify-check
      path: /verify/check/json
      description: Check a verification code.
      operations:
      - name: check-verification
        method: POST
        description: Confirm whether the user's PIN matches the sent code.
        inputParameters:
        - name: request_id
          in: body
          type: string
          required: true
          description: Verification request ID.
        - name: code
          in: body
          type: string
          required: true
          description: PIN entered by the user.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: verify-control
      path: /verify/control/json
      description: Cancel or trigger next verification event.
      operations:
      - name: control-verification
        method: POST
        description: Cancel a verification request or trigger next workflow.
        inputParameters:
        - name: request_id
          in: body
          type: string
          required: true
          description: Verification request ID.
        - name: cmd
          in: body
          type: string
          required: true
          description: 'Command: cancel or trigger_next_event.'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: vonage-numbers
    baseUri: https://rest.nexmo.com
    description: Vonage Numbers API for virtual number management.
    authentication:
      type: apikey
      key: api_key
      value: '{{VONAGE_API_KEY}}'
      placement: query
    resources:
    - name: account-numbers
      path: /account/numbers
      description: List owned phone numbers.
      operations:
      - name: list-owned-numbers
        method: GET
        description: Retrieve all inbound numbers associated with your Vonage account.
        inputParameters:
        - name: country
          in: query
          type: string
          required: false
          description: Filter by two-character country code.
        - name: size
          in: query
          type: integer
          required: false
          description: Number of results per page.
        - name: index
          in: query
          type: integer
          required: false
          description: Page index.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: number-search
      path: /number/search
      description: Search available numbers.
      operations:
      - name: search-available-numbers
        method: GET
        description: Find inbound numbers available for purchase.
        inputParameters:
        - name: country
          in: query
          type: string
          required: true
          description: Two-character country code.
        - name: type
          in: query
          type: string
          required: false
          description: 'Number type: landline, mobile-lvn, landline-toll-free.'
        - name: features
          in: query
          type: string
          required: false
          description: 'Required features: SMS, VOICE, MMS.'
        - name: pattern
          in: query
          type: string
          required: false
          description: Pattern to filter numbers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: number-buy
      path: /number/buy
      description: Purchase a phone number.
      operations:
      - name: buy-number
        method: POST
        description: Purchase a specific inbound number.
        inputParameters:
        - name: country
          in: body
          type: string
          required: true
          description: Two-character country code.
        - name: msisdn
          in: body
          type: string
          required: true
          description: Phone number to purchase (E.164).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: number-cancel
      path: /number/cancel
      description: Cancel a phone number.
      operations:
      - name: cancel-number
        method: POST
        description: Cancel subscription for a virtual number.
        inputParameters:
        - name: country
          in: body
          type: string
          required: true
          description: Two-character country code.
        - name: msisdn
          in: body
          type: string
          required: true
          description: Phone number to cancel.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: number-update
      path: /number/update
      description: Update number configuration.
      operations:
      - name: update-number
        method: POST
        description: Change the behavior of a number you own.
        inputParameters:
        - name: country
          in: body
          type: string
          required: true
          description: Two-character country code.
        - name: msisdn
          in: body
          type: string
          required: true
          description: Phone number to update.
        - name: mo_http_url
          in: body
          type: string
          required: false
          description: Inbound SMS webhook URL.
        - name: voice_callback_type
          in: body
          type: string
          required: false
          description: 'Voice routing type: sip, tel, app.'
        - name: voice_callback_value
          in: body
          type: string
          required: false
          description: Voice routing destination.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8082
    namespace: vonage-auth-api
    description: Unified REST API for Vonage phone authentication and number management.
    resources:
    - path: /v1/verifications
      name: verifications
      description: Manage phone verifications for 2FA.
      operations:
      - method: POST
        name: request-verification
        description: Send a verification code to a phone number.
        call: vonage-verify.request-verification
        with:
          number: rest.number
          brand: rest.brand
          code_length: rest.code_length
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/verifications/check
      name: verification-check
      description: Check a verification code.
      operations:
      - method: POST
        name: check-verification
        description: Verify a PIN submitted by the user.
        call: vonage-verify.check-verification
        with:
          request_id: rest.request_id
          code: rest.code
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/numbers
      name: numbers
      description: Manage virtual phone numbers.
      operations:
      - method: GET
        name: list-owned-numbers
        description: List owned virtual numbers.
        call: vonage-numbers.list-owned-numbers
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/numbers/available
      name: available-numbers
      description: Search available numbers.
      operations:
      - method: GET
        name: search-available-numbers
        description: Search for phone numbers available to purchase.
        call: vonage-numbers.search-available-numbers
        with:
          country: rest.country
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9092
    namespace: vonage-auth-mcp
    transport: http
    description: MCP server for AI-assisted phone verification and number management.
    tools:
    - name: request-verification
      description: Send a verification code to a phone number for 2FA.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: vonage-verify.request-verification
      with:
        number: tools.number
        brand: tools.brand
        code_length: tools.code_length
      outputParameters:
      - type: object
        mapping: $.
    - name: check-verification
      description: Verify a PIN code entered by the user to complete 2FA.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: vonage-verify.check-verification
      with:
        request_id: tools.request_id
        code: tools.code
      outputParameters:
      - type: object
        mapping: $.
    - name: cancel-verification
      description: Cancel a pending verification request.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: vonage-verify.control-verification
      with:
        request_id: tools.request_id
        cmd: cancel
      outputParameters:
      - type: object
        mapping: $.
    - name: list-owned-numbers
      description: List all virtual phone numbers owned by the account.
      hints:
        readOnly: true
        idempotent: true
      call: vonage-numbers.list-owned-numbers
      outputParameters:
      - type: object
        mapping: $.
    - name: search-available-numbers
      description: Search for available phone numbers to purchase in a country.
      hints:
        readOnly: true
        idempotent: true
      call: vonage-numbers.search-available-numbers
      with:
        country: tools.country
        type: tools.type
      outputParameters:
      - type: object
        mapping: $.
    - name: buy-number
      description: Purchase a virtual phone number for the account.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: vonage-numbers.buy-number
      with:
        country: tools.country
        msisdn: tools.msisdn
      outputParameters:
      - type: object
        mapping: $.