Getting started

• Introduction
• API Scope
• Subscribe to the API
• API Authentication
• API Description
  • Summary of resources
  • Summary of methods and URL
  • Summary of request body parameters
  • verify operation description
    • Request
    • Response
    • Fields description
  • device phone number operation description
    • Request
    • Response
    • Fields description
  • Most frequent errors
• History of document

Introduction

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

API Scope

The current API implementation is applicable for Live Trials with Orange Belgium (preselected list of MSISDN).

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 Front-end flow 3-Legged OAuth.

In short, this API uses Authorization by code (aka three-legged OAuth) mechanism as the final user of the service is requested to give their consent in order to authorize this client application to access their resources.

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

To authenticate the end-user and obtain her/his consent a GET request must be sent to the authorize endpoint from the user device. It is mandatory to provide a scope in this request. Orange implementation follows the CAMARA scope definition. The scope must be set to: dpv:<dpvValue>#<technicalParameter>. dpv stands for Data Privacy Vocabulary.

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

For 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 dpv:FraudPreventionAndDetection number-verification:verify
• to obtain the MSISDN, the scope in the authorize must be set to the individual scop openid dpv:FraudPreventionAndDetection number-verification:device-phone-number:read.

Please note that a global scope dpv:FraudPreventionAndDetection number-verification is also defined and gives access to all resources.

Once the end-user provides her/his consent, the Orange authorization server returns to the client application an authorization code.

Example of the request:

curl -X 'GET' \
  'https://api.orange.com/openidconnect/be/v1/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&code_challenge=ESpyXi9OQuAyD4Ocj44hwcdKsoHnaUWBvJ7yFhXlFOg&code_challenge_method=S256' \
  -H 'accept: */*'

          
          Copied 
        

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.

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

Example of the request:

curl  -X POST \
  'https://api.orange.com/openidconnect/be/v1/token' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic YWg0OWJOWWl4NUgzWWNvN...eWg1aw==' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'redirect_uri=https://webhook-muppet.apps.fr01.paas.diod.orange.com/hooks/8816...64/openid/create' \
  --data-urlencode 'code=OFR-SYPXPfaUPCrq...5uiiFf7wy9N6sO' \
  --data-urlencode 'code_verifier=SanFranciscoGiants'

          
          Copied 
        

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.

Go up

API Description

This API is based on version 1.0.0 of the API number-verification.

Summary of resources

This API has two resources verify and device-phone-number.

Summary of methods and URL

Summary of request body parameters

verify operation description

Verifies if the 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 with the access token.

Request

Using plain text phone number:

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

          
          Copied 
        

Using hashed phone number:

curl -X POST "https://api.orange.com/camara/obe/number-verification/v0/verify"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
"hashedPhoneNumber": "4f38c37545943a33833fbce1e53f84d79e1029b099901815c5074f9f8a877551"
}

          
          Copied 
        

Note: as the phone number is identified via the access token, following body example works as well:

curl -X POST "https://api.orange.com/camara/obe/number-verification/v0/verify"
...
-d  '

          
          Copied 
        

Response

200 
Content-Type: application/json

          
          Copied 
        

{
  "devicePhoneNumberVerified": true
}

          
          Copied 
        

Fields description

The response features only one attribute: devicePhoneNumberVerified.

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

device phone number operation description

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

Request

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

          
          Copied 
        

Response

200 
Content-Type: application/json

          
          Copied 
        

{
  "devicePhoneNumber": "+32493456721"
}

          
          Copied 
        

Fields description

The response features only one attribute: devicePhoneNumber. In order to be globally unique it is formatted in international format, according to E.164 standard, prefixed with '+'.

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"
}

          
          Copied 
        

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"
}

          
          Copied 
        

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"
}

          
          Copied 
        

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

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: ..."
}

          
          Copied 
        

Go up

History of document

Note: version of the document is different than version of the API.

Go up