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

For NumberVerification the API provider guarantees that there is no user interaction. Would user interaction be needed the authorization server returns an error. 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.

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 either:

• Sends a CIBA Authentication Request, as described in the current release CAMARA APIs Access and User Consent Management, with a parameter login_hint=operatortoken:<temporary token>.
• Or sends a JWT-Bearer token request as described in CAMARA APIs Access and User Consent Management, with the TS.43 token in the sub claim of the JWT assertion with the format "operatortoken:<temporary token>".

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.

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.

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.

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.

Additional CAMARA error responses

The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in CAMARA API Design Guide.

Please refer to the CAMARA_common.yaml of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the API Readiness Checklist document associated to this API version.

As a specific rule, error 501 - NOT_IMPLEMENTED can be only a possible error response if it is explicitly documented in the API.

Apache 2.0

Project documentation at CAMARA