This API provides methods to obtain the capabilities of CAMARA project in mas-stack.

This API can verify or retrieve the mobile phone number that is currently allocated by the network operator to the SIM in the end user's device

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

Introduction

The Number Verification API is used by the API consumer to perform real-time checks to verify the phone number of a mobile device being used to access the application. This check can be done either by the API provider, returning "true" or "false", or by the application, by matching the phone number returned by the API Provider with the phone number of the device that is being used.

It uses silent authentication (Network-based authentication or SIM-Based authentication) to verify possession of a phone number in the background without requiring user interaction. There are neither one-time passwords (OTP) 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 is not spoofed or cloned.

Relevant Definitions and Concepts

• Network-Based Authentication: Authentication mechanism based on the identification of the mobile phone. A network operator knows to which subscriber a connected mobile phone belongs and what its associated phone number is.
• SIM-Based Authentication: Authentication mechanism based on the identification of the subscriber's SIM installed in the user's device. This mechanism relies on temporary tokens provided by the operator, as defined by GSMA TS.43 and GSMA ASAC.

API Functionality

This API enables an API Consumer to verify or retrieve the phone number of the mobile device being used to access their service.

The Authentication Request

Authentication Request with a temporary token

If the API Consumer has a TS.43 temporary token created on the mobile device then this API works over all connections e.g. WiFi taking advantage of the SIM-Based authentication. The API Consumer sends the temporary token to their backend which sends a CIBA Authentication Request, as described in the current release CAMARA APIs Access and User Consent Management, with a parameter "login_hint=operatortoken:". How the API Consumers get a TS.43 temporary token and how this token is sent to their backend, is out-of-scope of the API definition.

Authentication Request without a temporary token

If the API Consumer does not have a TS.43 temporary token then the API Consumer must use OpenId Connect Authorization Code Flow as described in the current release of CAMARA APIs Access and User Consent Management. For this method of authentication to work, the device must be connected to the mobile network.

Resources and Operations overview

This API currently provides two endpoints which both require a 3-legged token obtained by using one of the two methods indicated in The Authentication Request section. This therefore excludes using, for example, SMS/OTP or user/password as an authentication method:

• The /verify endpoint checks whether the mobile phone number registered by the user with the API consumer matches the one actually associated with the mobile device. It can receive either a hashed or a plain text phone number as input. It compares the received phone number with the user's phone number associated to the access token in order to respond true/false.
• The /device-phone-number endpoint returns the phone number associated by the network operator with the SIM in the end user's device.

Sequence Diagram

The following sequence diagram shows an example of a direct integration into the developer's application and the API Provider's Authorization Server and API for the case that no temporary token is available.

Implementation 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.

  The API Consumer should use the request parameter prompt=none in the Authentication Request, as described in OIDC Connect, ensuring no user interaction.

  The API Provider implies the request parameter prompt=none in the Authentication Request for this API.

• (2): The way in which the phone number is retrieved depends upon the implementation. For example, the access token may be a self-contained encrypted JWT, and so the API provider can decrypt and identify phone number directly from the access token. Other implementations might retrieve the phone number associated with the access token from their Authorization Server.

Authorization and authentication

The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management for the released version of the profile.

The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.

In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.

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.

This API provides the consumer with the ability to verify the location of a device.

API consumers are able to verify whether the location of a certain user device is within the area specified. Currently the only area supported as input is a circle determined by a set of coordinates (latitude and longitude) and some expected accuracy (radius).

This is the MasStack internal contract, consumed by the API Manager, which builds the request from the authenticated context (the phoneNumber is resolved from the token) and the validated CAMARA request. It follows the same internal convention as Location Retrieval.