{
   "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](/verify/guides/silent-authentication/number-verification-migration), such as the [Number Verification API](https://developer.vonage.com/en/number-verification/overview), increasing performance, privacy and security:\n",
      "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"
                        }
                     ]
                  }
               }
            }
         }
      }
   }
}