Number Verification

Introduction

The CAMARA Number Verification API performs real-time checks on the phone number associated with an Orange mobile line on the Orange mobile network. It reveals if the user is using a device with the same mobile phone number as the one which is declared.

API Scope

Current API implementation covers all Orange Spain and Jazztel mobile lines.

Subscribe to the API

You get the Authorization header credentials when you register your application on the Orange Developer Console.

API Authentication

HTTPS requests to the REST API are protected with 3-Legged OAuth.

In short, the API Invoker (e.g. Application Backend or Aggregator) before to request SIM swap check, needs to request a Three-Legged Access Token from Orange Authorization Server.

Step 1: request the OAuth authorization code from the user device

Firstly, the API invoker (for example, the Application Backend) instructs the Application on the Consumption Device to initiate the OIDC Authorization Code Flow with the Operator. The authorization request includes the client_id of the ASP's Application requesting access to the API and the Application's redirect_uri (invoker_callback) where the authorization code will be sent.

It is mandatory to provide a scope in this request. Orange implementation follows the CAMARA scope definition. The scope must be set to: openid dpv:<dpvValue> <technicalParameter>.

• dpv stands for Data Privacy Vocabulary.
• technical parameters are the data claims by the API consumer - for example in this API there are 2 possible values: number-verification:verify and number-verification:device-phone-number:read

For the current implementation only FraudDetectionAndPrevention dpv value is managed which means that:

• to check the msisdn, the scope in the authorize must be set to the individual scope openid dpv:FraudPreventionAndDetection number-verification:verify
• to obtain the msisdn, the scope in the authorize must be set to the individual scope openid dpv:FraudPreventionAndDetection number-verification:device-phone-number:read

As user consent is not required, Orange Exposure Platform will continue the authorization code flow by redirecting to the Application's redirect_uri (invoker_callback) and including the authorization code (OperatorCode).

Here an example of request:

curl -X 'GET' \
  'https://api.orange.com/es/openapi/oauth/v2/authorize?response_type=code&client_id=yourCliendId&state=yourState&redirect_uri=https%3A%2F%2Fwebhook-muppet.apps.fr01.paas.diod.orange.com%2Fhooks%2F8816...64%2Fopenid%2Fcreate&scope=openid%20dpv%3AFraudPreventionAndDetection%20number-verification%3Averify' \
  -H 'accept: */*'

Step 2: Request the OAuth access token

Once the client application got the authorization code, it has to get the access token protecting the resources. In order to retrieve it, the client application triggers a POST request to the token endpoint.

In the /token, for client authentification, the API consumer MUST authenticate with the authorization server using Basic authentication.

If the transaction succeeds, in the POST response, the acccess_token is provided.

Here an example of request:

curl  -X POST \
  'https://api.orange.com/es/openapi/oauth/v2/token' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=eyJhbGciOi...zif0Tjxzw' \
  --data-urlencode 'auth_req_id=69957d77-...-b29f22e61307' \
  --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'

Response:

200
Content-Type: application/json

{
  "access_token": "28FpNfX...7lwFAg3LR0vmHCOmJAg7Si",
  "token_type": "Bearer",
  "expires_in": 119,
}

Step 3: Access protected resources using OAuth access token

In order to call our API, the access_token is mandatory.

Specific documentation about number verification resources is provided below.

API Description

Summary of resources

This API has two resource verify and device-phone-number

Summary of methods and URL

Verification Operation

Verifies if provided phone number (plain text or hashed format) matches the one that the user is currently using. The API returns true/false depending on if the input matches the authenticated user's device phone number associated to the access token.

Request phone number verification

Request

Using plain text phone number:

curl -X POST "https://api.orange.com/camara/oes/number-verification/v1/verify"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
"phoneNumberType": "RegularPhoneNumber",
"phoneNumber": "+34123456789"
}'

Using hashed phone number:

curl -X POST "https://api.orange.com/camara/oes/number-verification/v1/verify"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
"phoneNumberType": "HashedPhoneNumber",
"phoneNumber": "32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba"
}'

Fields description

As the request could be done with a plain text or a hashed phone number, it is requested to provide phoneNumberType attribute to specify phone number format

2 values for phoneNumberType are managed:

• RegularPhoneNumber or REGULAR - in this case the phone number must be pass in E.164 format (starting with country code). Optionally prefixed with '+'.
• HashedPhoneNumber or HASHED - in this case the Hashed phone number must be a SHA-256 (in hexadecimal representation) of the mobile phone number in E.164 format (starting with country code)

Depending on this type, the second attribute phoneNumber must be valued accordingly.

Response

200
Content-Type: application/json

{
  "devicePhoneNumberVerified": true
}

Fields description

The response features only one attribute: devicePhoneNumberVerified.

This attribute is boolean indicating if a phone number provided correspond to the one associated with the access token.

Return phone number Operation

Returns the phone number associated with the access token so the API clients can Verification the number themselves.

Note: this operation is not available for local privacy regulations.

Request phone number

Request

curl -X GET "https://api.orange.com/camara/oes/number-verification/v1/device-phone-number"
-H "Authorization: Bearer {your access token}"
-H 'accept: application/json'

Response

200
Content-Type: application/json

{
    "devicePhoneNumber": {
        "phoneNumberType": "REGULAR",
        "phoneNumber": "34123456789"
    }
}

Fields description

The response features devicePhoneNumber structure with two attributes: phoneNumberType to specify if the phone number value is a plain text or a hash, and phoneNumber which is the value itself.

Most frequent errors

Most frequent errors for this API are related to insufficient permission (code 403). In addition to regular scenario of PERMISSION_DENIED, other scenarios may exist:

• Client authentication was not performed via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password ({"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK","message": "Client must authenticate via the mobile network to use this service"})
• Phone number cannot be deducted from access token context.({"code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"})

Permission denied:

HTTP/1.1 403 Error: bad Request
Content-Type: application/json

{
  "code": "PERMISSION_DENIED",
  "status": "403",
  "message": "Client does not have sufficient permissions to perform this action"
}

User not authenticated by Orange mobile network:

HTTP/1.1 403 Error: bad Request
Content-Type: application/json

{
  "status": 403,
  "code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK",
  "message": "Client must authenticate via the mobile network to use this service"
}

Invalid access token:

HTTP/1.1 403 Error: bad Request
Content-Type: application/json

{
  "status": 403,
  "code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT",
  "message": "Phone number cannot be deducted from access token context"
}

There are some cases where your client application will no longer gain access to API resources, and get an error back.

Please check the following points:

• Here, you attempt to use an expired or revoked access_token and you get an invalid token error. You will have to request a new access_token. As an example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "code": "UNAUTHORIZED",
  "message": "Authorization failed: ..."
}