Service Enabling Network Function API to verify that the provided mobile phone number is the one used in the device. It verifies that the user is using a device with the same mobile phone number as it is declared. It also makes it possible for a Service provider to verify the number itself by returning the phone number associated to the authenticated user's access token.

In this API phone number term refers to the mobile phone number

Introduction

Number Verification API performs real-time checks to verify the phone number of the mobile device being used to access a service provider (SP) service, where the mobile device is accessing the service provider over a mobile network (WiFi connections are out of this API scope) either by getting the comparison result or receiving the phone number of the device that it is used, so they can verify it themselves.

It uses direct mobile network connections to verify possession of a phone number in the background without requiring user interaction. There are neither OTPs (One-time passwords) received by SMS nor authenticator app downloads, so it is much simpler. It can be used at sign up, login, or transaction time to validate that a user's SIM (Subscriber Identity Module) is both actively connected to the mobile network and not spoofed or cloned.

Relevant Definitions and Concepts

• Network-Based Authentication: Authentication mechanism based on the identification of the endpoint of a network connection. Network operators know to which user a network resource is assigned at a given moment, for example the mobile phone number associated to a specific mobile network connection.

API Functionality

This enables a Service Provider (SP) to verify the phone number of the mobile device being used to access their service where the mobile device is accessing the service provider over a mobile network (WiFi connections are out of this API scope). This can happen either by getting the comparison result or receiving the phone number of the device that is used, so they can verify it themselves.

Resources and Operations overview

This API currently provides two endpoints where both require a 3-legged token and authentication via mobile network (excluding for example by SMS/OTP or user/password as an authentication method):

• The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed or a plain text phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond true/false.
• The next one retrieves the phone number associated to the user's token and returns it so the verification can be made by the service provider.

Sequence Diagram

Number Verification API uses the standard OAuth2 Authorization Code grant. The following diagram will help to clarify the end-to-end process, including previous steps prior to this API call.

Additional details:

• (1): Authentication must be automatic without any user interactions. Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App. So it is required to be authentication via mobile network and without the user being involved. the use of parameter prompt=none, as described in OIDC Connect, ensures no user interaction.

• (2): The way in which the phone_number is retrieved depends on the implementation. For example, access token may be a self contained encrypted JWT, so API can decrypt and identify phone_number. Some other implementations might request the phone_number associated to the token from Authserver.

Authorization and authentication

CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document CAMARA-API-access-and-user-consent.md. Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.

In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. The API client must authenticate on behalf of a specific user to use this service. This must be done via mobile network authentication.

Further info and support

GSMA Mobile Connect Verified MSISDN specification was used as source of input for this API. For more about Mobile Connect, please see Mobile Connect website.