updated nv doc , need revision

Author: adritid

v0/catalog/numberverification/images/NV(3).png

@@ -18,10 +18,9 @@ content:
   <span style={{backgroundColor: '#8a8a8a', color: 'white', borderRadius: '15px', padding: '4px 12px', fontSize: '12px', fontWeight: 'bold'}}>GSMA Certified API</span>
 </div>
 
-Built as part of the Open Gateway initiative, the Number Verification API provides developers with universal access to essential network functionalities. Whether you're enhancing user registration processes, securing transactions, or optimizing user engagement strategies, integrating the Number Verification API enriches your application's security posture while ensuring a seamless user experience.
+The Number Verification API is part of the Open Gateway initiative, providing developers with access to network-based phone number validation. This API verifies user identity by confirming phone number ownership through network operator mechanisms, eliminating the need for manual verification processes.
 
-> 📘 Want to give it a try?
-> Apply to join the [Developer Hub](https://opengateway.telefonica.com/en/developer-hub/join) and gain access to our Sandbox.
+Apply to join the [Developer Hub](https://opengateway.telefonica.com/en/developer-hub/join) and gain access to our Sandbox.
 
 ### Getting started on the Telefónica Open Gateway Sandbox
 
@@ -36,37 +35,102 @@ Built as part of the Open Gateway initiative, the Number Verification API provid
   allowfullscreen>
 </iframe>
 
-## Overview of the Number Verification CAMARA API
+## API Overview
 
-### High level definition
+### Technical Definition
 
-The Number Verification CAMARA API validates user identity by confirming ownership of the phone number being registered, matching it with the number identified by the operator through the user’s device connection.
+The Number Verification CAMARA API validates user identity by confirming that the provided phone number matches the number associated with the user's device connection to the mobile network operator.
 
-### API Operations
+### Available Operations
 
-The Number Verification CAMARA API specifies the following two operations:
-
-- **POST verify:** Determines if the provided phone number matches the one currently in use by the user (parameter `phoneNumber`). This operation is ideal for user authentication.
+- **POST verify:** Validates if the provided phone number matches the device's registered number. Returns a boolean result indicating verification status.
 
 	[Check the API Reference](/reference/phonenumberverify-2)
 
-- **GET device-phone-number:** Identifies the phone number currently associated with the user's device without requiring input, providing a straightforward way to retrieve this information.
+- **GET device-phone-number:** Retrieves the phone number associated with the user's device without requiring input parameters.
 
 	***This feature is pending availability***
 
-The Number Verification CAMARA API enables developers to seamlessly integrate authentication mechanisms into their applications, enhancing the user experience and security. It can also be combined with other Open Gateway APIs focused on anti-fraud measures to further bolster security.
 
-Integration with channel partners and service aggregators streamlines the incorporation of telco functionalities with additional security algorithms, backup authentication methods, or external data sources. This collaboration enhances service reliability and security, leveraging APIs like Device Location Verification or SIM SWAP within the Open Gateway framework.
+### Technical Implementation
+
+The API leverages network operator infrastructure to perform verification without requiring user interaction. This network-based approach provides:
+
+- Real-time validation against operator records
+- No dependency on SMS or voice calls
+- Transparent verification process for end users
+- Integration with existing network authentication mechanisms
+
+The API can be combined with other Open Gateway APIs such as Device Location Verification or SIM SWAP detection to create comprehensive security solutions.
+
+### Why Frontend-Initiated Authentication is Required
+
+The Number Verification API uses **Authorization Code Flow** (frontend-initiated) instead of **CIBA (Client Initiated Backchannel Authentication)** for a critical technical reason:
+
+**IP Address Verification**: The core verification mechanism compares the phone number being verified against the IP address that the mobile network operator has assigned to that specific SIM card. This comparison can only be performed when the request originates from the user's mobile device.
+
+**Technical Implementation**:
+- When a user's device connects to the mobile network, the operator assigns a specific IP address to that SIM card
+- The verification request must come from this assigned IP address to establish the connection between the phone number and the device
+- If the request originates from your backend server, the operator sees your datacenter's IP address instead of the user's mobile IP
+- This breaks the verification chain, as there's no way to correlate your server's IP with the user's phone number
+
+**Why CIBA Cannot Work for Number Verification**:
+- CIBA flows are backend-initiated and use the server's IP address
+- The mobile operator cannot establish a relationship between your server's IP and the user's phone number
+- The fundamental verification mechanism (IP-to-phone-number matching) becomes impossible
+
+This architectural requirement ensures that verification is truly tied to the physical device and SIM card being used, providing authentic network-level validation that cannot be spoofed or bypassed.
+
+## Use Cases and Benefits
+
+Traditional verification methods using SMS or voice calls are vulnerable to SIM swapping, interception, and social engineering attacks. The Number Verification API addresses these security challenges through network-level validation.
 
-## Why Number Verification?
 ![NumberVerification Before](https://github.com/Telefonica/opengateway-developers-website/raw/main/v0/catalog/numberverification/images/NV(1).png)
 
-In today's digital landscape, verifying phone number ownership is critical to prevent identity fraud and secure online transactions. The Number Verification CAMARA API offers a reliable solution to **authenticate users by confirming their phone numbers**. This ensures that only legitimate users gain access to digital services, bolstering security measures and building trust among customers.
+The Number Verification API provides network-level authentication that validates phone number ownership through the mobile operator's infrastructure, offering superior security compared to conventional methods.
 
 ![NumberVerification After](https://github.com/Telefonica/opengateway-developers-website/raw/main/v0/catalog/numberverification/images/NV(2).png)
 
-### How does the Number Verification API help facilitate authentication? 
 
-The Number Verification API utilizes telco mechanisms to authenticate users seamlessly based on their device's connection to the network. This method contrasts with traditional authentication solutions by enhancing user convenience and security. Unlike manual processes or plain-text codes, network-based validation requires no user interaction, bolstering protection against unauthorized access.
 
-This API verifies that the provided mobile phone number (MSISDN) matches the device initiating data communication, ensuring users interact with digital services from authenticated devices.
+For desktop applications, the Number Verification API supports cross-device authentication through QR code scanning, enabling users to verify their phone number from their mobile device while using a desktop application.
+
+![NumberVerification Desktop](https://github.com/Telefonica/opengateway-developers-website/raw/main/v0/catalog/numberverification/images/NV(3).png)
+
+### Key Advantages
+
+**Network-Based Verification:** Utilizes the mobile network operator's authentication mechanisms, providing verification without user interaction or exposure to interception.
+
+**Real-Time Validation:** Immediate confirmation of phone number ownership through active network connection verification.
+
+**Enhanced Security:** Eliminates vulnerabilities associated with SMS-based verification, including SIM swapping and message interception.
+
+**Seamless Integration:** RESTful API design enables straightforward integration into existing authentication workflows.
+
+The API verifies that the provided mobile phone number (MSISDN) corresponds to the device establishing the data connection, ensuring users access services from authenticated devices.
+
+
+### Network-Level Authentication Mechanism
+
+The Number Verification API performs authentication through **network infrastructure validation**:
+
+**Core Verification Process**:
+1. **IP Address Correlation**: The mobile operator identifies which SIM card is assigned to the IP address making the request
+2. **Phone Number Matching**: The operator compares the provided phone number with the SIM card associated with that IP address
+3. **Real-Time Validation**: This comparison happens instantly using live network data, not stored databases
+
+**Technical Advantages**:
+- **No User Interaction Required**: Verification is transparent to the end user
+- **Immune to SIM Swapping**: Uses current network connection, not historical data
+- **Cannot Be Intercepted**: No SMS or voice calls that can be redirected
+- **Spoofing-Resistant**: Requires actual network connection from the specific SIM card
+
+**Key Advantages Over Traditional Methods**:
+- **Network-Based Verification**: Utilizes mobile operator authentication mechanisms without user interaction
+- **Real-Time Validation**: Immediate confirmation through active network connection verification  
+- **Enhanced Security**: Eliminates SMS/voice vulnerabilities including SIM swapping and interception
+- **Seamless Integration**: RESTful API design for straightforward authentication workflow integration
+- **Spoofing-Resistant**: Requires actual network connection from the specific SIM card
+
+This verification confirms that the provided mobile phone number (MSISDN) corresponds to the SIM card currently establishing the data connection, ensuring authentic device-to-identity binding.

v0/catalog/numberverification/numberverification.md

@@ -10,11 +10,20 @@ content:
     the one on the SIM card installed in the end-user's device.
 ---
 
-Although the API consumption flow for this API must be always triggered from such end-user's device - therefore from the application's frontend - according to its intrinsic feature, the flow will always complete on the backend. The following code shows, for didactic purposes, a hypothetical or sample SDK used on the backend, in several programming languages, from a generic Open Gateway's channel partner, also known as aggregator.
+## Implementation Architecture
 
-The final implementation will depend on the channel partner's development tools offering. Some of them might even provide you with both backend SDKs and frontend SDKs, the latter handling details such as network interface switching for proper mobile line identification. Apart from this extra frontend features (available upon channel partner discretion), note that channel partners' Open Gateway SDKs are just code modules wrapping authentication and API calls providing an interface in your app's programming for convenience.
+The Number Verification API uses a **frontend-initiated, backend-completed** authentication flow:
 
-Sample code on how to consume the API without an SDK, directly with HTTP requests, is also provided, and it is common and valid no matter what your partner is, thanks to the CAMARA standardization. If you do not use an SDK you need to code the HTTP calls and additional stuff like encoding your credentials, calling authorization endpoints, handling tokens, etc. You can check our sample [Postman collection](https://github.com/Telefonica/opengateway-postman) as a reference.
+- **Frontend starts**: The verification request must originate from the user's mobile device to establish network identity
+- **Backend completes**: The authentication flow concludes on your backend server for security reasons (protecting client credentials)
+
+This split architecture ensures both network-based verification and secure credential management.
+
+## SDK vs HTTP Implementation
+
+**Channel Partner SDKs**: Most aggregators provide SDKs that simplify authentication and API calls. Some offer both frontend and backend SDKs, with frontend SDKs handling network interface switching for proper mobile line identification.
+
+**Direct HTTP Calls**: You can also consume the API directly using HTTP requests. This approach requires manual handling of credential encoding, authorization endpoints, and token management. Reference our [Postman collection](https://github.com/Telefonica/opengateway-postman) for HTTP examples.
 
 > 📘 Want to give it a try before coding?
 > Check the [API interactive reference](https://developers.opengateway.telefonica.com/reference/phonenumberverify)
@@ -28,19 +37,31 @@ Sample code on how to consume the API without an SDK, directly with HTTP request
 
 ## Code samples
 
-> 📘 Note
-> These are code samples and not finalized ready-to-run code:
-> - Remember to replace 'my-app-id' and 'my-app-secret' with the credentials of your app.
-If you registered your test app on our Sandbox, you can retrieve its credentials [here](https://sandbox.opengateway.telefonica.com/my-apps). 
-> - Remember also to replace "aggregator/opengateway-sdk" with the SDK from your aggregator.
-If you are using our sandbox SDK, check info and installation of de Sandbox SDK [here](/docs/sdkreference)
+**Important Notes:**
+- Replace `my-app-id` and `my-app-secret` with your actual application credentials
+- If using our Sandbox, retrieve credentials [here](https://sandbox.opengateway.telefonica.com/my-apps)
+- Replace `aggregator/opengateway-sdk` with your aggregator's actual SDK package name
+- For our Sandbox SDK, check installation details [here](/docs/sdkreference)
 
 ### Frontend
 
-This API consumption flow must always start on the end-user's device, since its feature is precisely verifying that a given phone number is the one effectively used in such device, which can be verified by the operator by receiving the online request from it:
-* Application's frontend performs an HTTP request to get a `code`, and provides a `redirect_uri` it wants such `code` to be redirected to.
-* Application's frontend will receive an HTTP redirect (status 302) and needs to be able to handle it. If it is a web application running on a web browser, the browser will natively follow the redirection. If it is not, in depends on the coding language and/or HTTP module or library used, or on its settings, how the flow will follow all the way to your application's backend through the mobile network operator authentication server.
-* Application's backend receives the `code` from this HTTP redirection, by publishing an endpoint in the given `redirect_uri`, and then exchanges it for an access token. The latter is achieved as shown in the [Backend](#backend) flow.
+#### Why the Frontend Must Initiate the Flow
+
+The Number Verification API must start from the end-user's device because:
+- **Network Identity**: The mobile operator needs to identify which SIM card/phone number is making the request
+- **Device Context**: Verification works by confirming the phone number matches the device's active mobile connection
+- **Security**: The network-based authentication happens through the user's actual mobile data connection
+
+#### Frontend Flow Steps
+
+1. **Initiate Request**: Your frontend application makes an authorization request to the mobile operator
+2. **Provide Callback**: You specify a `redirect_uri` (your backend callback URL) where the operator will send the authorization code
+3. **Handle Redirect**: The mobile operator redirects to your callback URL with an authorization code
+4. **Backend Processing**: Your backend receives the code and completes the token exchange (see [Backend](#backend) section)
+
+**Important**: The `redirect_uri` must point to your backend server, not your frontend application, because:
+- The authorization code must be securely exchanged for an access token using your client secret
+- Client secrets should never be exposed in frontend code for security reasons
 
 The authentication protocol used in Open Gateway for frontend flows is the OIDC standard Authorization Code Flow. You can check the CAMARA documentation on this flow [here](https://github.com/camaraproject/IdentityAndConsentManagement/blob/release-0.1.0/documentation/CAMARA-API-access-and-user-consent.md#authorization-code-flow-frontend-flow).
 
@@ -109,7 +130,23 @@ fetch(url, requestOptions);
 
 ### Backend
 
-As the opposite to the flow triggering, this API consumption flow will always complete on the application's backend, since the authorization code is to be received via HTTP redirect on your redirect_uri, aka callback URL, which must be published on a web server.
+#### Understanding the Callback URL Requirement
+
+The Number Verification API uses the OAuth 2.0 Authorization Code Flow for security purposes. Here's why a callback URL is essential:
+
+**Why a callback URL is needed:**
+- **Security**: Your app's credentials (client secret) must remain secure and never be exposed to the frontend/browser
+- **Token Exchange**: The authorization code received from the mobile operator must be exchanged for an access token on your secure backend
+- **Network Verification**: The mobile operator needs to redirect back to your application after verifying the user's network connection
+
+**How the callback URL works:**
+1. Your frontend initiates the verification request
+2. The user's device connects to the mobile operator for network-based authentication
+3. The operator redirects back to your `redirect_uri` (callback URL) with an authorization code
+4. Your backend receives this code and exchanges it securely for an access token
+5. The access token is then used to call the verification API
+
+The callback URL must be a publicly accessible endpoint on your backend server that can handle HTTP GET requests with query parameters.
 
 #### Getting the access token from the callback endpoint at the backend
 
@@ -256,7 +293,7 @@ app.get('/numberverification-callback', (req, res) => {
     let accessToken
 
     const myHeaders = new Headers()
-    myHeaders.append("Content-Type", "application/x-www-form-urlencode")
+    myHeaders.append("Content-Type", "application/x-www-form-urlencoded")
     myHeaders.append("Authorization", `Basic ${appCredentials}`)
     const requestBody = JSON.stringify({
         "grant_type": "authorization_code",
@@ -342,4 +379,4 @@ fetch("https://opengateway.aggregator.com/number-verification/v0/verify", reques
 
     console.log(`Phone number ${verified ? "verified" : "does not match mobile line"}`)
   })
-```
+```