openapi: 3.0.1
info:
  title: Network Enablement
  description: >
    The Network Enablement API improves the existing authentication flow for
    Network APIs. This is especially beneficial for those APIs using [client
    authentication](/getting-started-network/guides/client-authentication), such
    as the [Number Verification
    API](https://developer.vonage.com/en/number-verification/overview),
    increasing performance, privacy and security:
  version: v1
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: https://developer.vonage.com/
servers:
  - url: https://api-eu.vonage.com
    description: Server url.
tags:
  - name: NetworkEnablement
    description: facilitates the integration of the Network APIs.
paths:
  /v0.1/network-enablement:
    post:
      description: Initiates the usage of Network APIs
      summary: Handle network enablement requests
      operationId: networkEnablement
      tags:
        - NetworkEnablement
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EnablementRequest"
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnablementResponse"
        "400":
          $ref: "#/components/responses/ErrorBadRequest"
        "401":
          $ref: "#/components/responses/ErrorUnauthorizedMissingCredentials"
        "415":
          $ref: "#/components/responses/ErrorInvalidContentType"
        "422":
          $ref: "#/components/responses/ErrorUnprocessableRequest"
        "500":
          $ref: "#/components/responses/ErrorInternalError"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    EnablementRequest:
      type: object
      required:
        - phone_number
        - scopes
        - state
      properties:
        phone_number:
          description: The phone number that will be used to authenticate the user.
          type: string
          example: "+442072068888"
        scopes:
          description: List of scopes used during the authentication process to define the
            specific actions a user is allowed to access.
          type: array
          minItems: 1
          maxItems: 1
          items:
            type: string
            example: dpv:FraudPreventionAndDetection#number-verification-verify-read
        state:
          description: A random string to identify each access token you generate.
          type: string
          example: tests-state-b3977c55-b4caa
    EnablementResponse:
      description: Network Enablement response
      type: object
      properties:
        scopes:
          type: object
          description: Requested scope responses
          properties:
            dpv:FraudPreventionAndDetection#number-verification-verify-read:
              $ref: "#/components/schemas/NumberVerificationRead"
          example:
            dpv:FraudPreventionAndDetection#number-verification-verify-read:
              app_url: null
              auth_url: https://api-eu.vonage.com/oauth2/auth
              requires_carrier_network: true
            dpv:FrandPreventionAndDetection#example-error-scope:
              error:
                title: Forbidden
                instance: bf0ca0-bf927b-3b52e3cb-03217e1a1ddf
                detail: The Network API application can only be used with verified phone
                  numbers. Blocked by allowlist.
                error_type: UNAUTHORIZED
    NumberVerificationRead:
      type: object
      description: Number Verification Read Scope Response
      oneOf:
        - $ref: "#/components/schemas/NumberVerificationReadSuccess"
        - $ref: "#/components/schemas/ScopeError"
    NumberVerificationReadSuccess:
      type: object
      description: Number Verification Read Scope Success
      properties:
        app_url:
          description: "[deprecated] If present, will always be null."
          type: string
        auth_url:
          description: Contains the URL to be sent to the frontend to start the
            authorization flow
          type: string
        requires_carrier_network:
          description: "[deprecated] Indicates that the call to auth_url must be made over
            the carrier network, rather than via Wifi. If present, always true."
          type: boolean
    ScopeError:
      type: object
      description: Scope Error
      properties:
        error:
          type: object
          properties:
            title:
              description: Error message
              type: string
            instance:
              description: Internal Trace ID
              type: string
            detail:
              description: Additional information about the error
              type: string
            error_type:
              type: string
              description: Type of error
    ErrorResponse:
      description: Error
      type: object
      required:
        - title
        - detail
      properties:
        type:
          type: string
          description: Link to error / remediation options
          format: uri
        title:
          description: Generic error message
          type: string
        detail:
          description: Additional information about the error
          type: string
        instance:
          description: Internal Trace ID
          type: string
  responses:
    ErrorUnauthorizedMissingCredentials:
      description: Missing or Invalid Credentials
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            type: https://developer.vonage.com/en/api-errors/#unauthorized
            title: You did not provide correct credentials.
            detail: Check that you're using the correct credentials, and that your account
              has this feature enabled
            instance: af0fa0bf92e1a2dd2e31acb07e1a1ddf
    ErrorBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            MalformedJson:
              value:
                type: https://developer.vonage.com/en/api-errors#invalid-json
                title: Malformed JSON
                detail: Malformed JSON payload
                instance: bf0ca0bf927b3b52e3cb03217e1a1ddf
            BadRequest:
              value:
                type: https://developer.vonage.com/en/api-errors#invalid-param
                title: Bad Request
                detail: number-verification requests are not supported to this destination
                  Carrier Network
                instance: bf0ca0bf927b3b52e3cb03217e1a1ddf
    ErrorInvalidContentType:
      description: Invalid Content-Type header
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            type: https://developer.vonage.com/en/api-errors#content-type-header
            title: Invalid Content-Type header
            detail: "Invalid Content-Type header provided. Must be one of the following:
              'application/json'"
            instance: af0fa0bf92e1a2dd2e31acb07e1a1ddf
    ErrorInternalError:
      description: Internal Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            type: https://developer.vonage.com/en/api-errors
            title: Internal error
            detail: Internal error
            instance: bf0ca0bf927b3b52e3cb03217e1a1ddf
    ErrorUnprocessableRequest:
      description: Unprocessable Content
      content:
        application/problem+json:
          schema:
            description: Error response
            type: object
            properties:
              title:
                type: string
                description: Error title.
              type:
                type: string
                description: Link to documented error type.
              instance:
                type: string
                format: uuid
                description: UUID reference for the instance.
              detail:
                type: string
                description: More detailed error descriptions.
              invalid_parameters:
                type: array
                description: Detailed array of errors.
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    reason:
                      type: string
          example:
            title: Invalid param
            detail: The value of one or more parameters is invalid
            type: https://developer.vonage.com/api-errors#invalid-param
            instance_id: bdfa1452-0f4d-4d06-8e9f-e00cca4a68b3
            invalid_parameters:
              - name: state
                reason: must not be blank
