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
- check sim swap operation description
- Request
- Response
- Fields description
- retrieve-date sim swap operation description
- Request
- Response
- Fields description
- Most frequent errors
- History of document
Introduction
This API informs you whether a SIM change has occurred recently for a user, thereby reducing fraud risk.
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 CIBA 3-Legged OAuth.
In short, the API Invoker (e.g. Application Backend or Aggregator) before requesting SIM swap check, needs to request a Three-Legged Access Token from Orange Authorization Server. The process follows the OpenID Connect Client-Initiated Backchannel Authentication (CIBA) flow.
Step 1: request the OAuth authorization code from the user device
The API Invoker provides in the authorization request (/bc_authorize) a login_hint with a valid User identifier together with the application credentials (client_assertion & client_assertion_type) and indicates the Purpose for processing Personal Data. The Orange implementation follows the CAMARA scope definition. The scope must be set to: opendid dpv:<dpvValue> <technicalParameter>
. dpv
stands for Data Privacy Vocabulary.
Note on JWT usage via client assertion: client_assertion
is a JWT used by a client to authenticate itself to an authorization server, while client_assertion_type
specifies the type of assertion being used, typically indicating it is a JWT. Together, they facilitate secure client authentication in OAuth 2.0 and OpenID Connect protocols. API consumer as to define JWK keystore in settings tab of the application in Orange Developer
For current implementation, only FraudDetectionAndPrevention
dpv value is managed, which means that:
- to check the SIM Swap date the scope in the
bc-authorize
must be set toopenid dpv:FraudPreventionAndDetection sim-swap:check
- to get the latest SIM Swap date the scope in the
bc-authorize
must be set toopenid dpv:FraudPreventionAndDetection sim-swap:retrieve-date
.
Please note that a global scope openid dpv:FraudPreventionAndDetection sim-swap
is also defined and gives access to all resources.
Orange Authorization Server will check if the owner of the phone number did not opted-out to authorize access to this data. If this is not the case a response 200 is sent back with a authorization request identifier (auth_req_id
). If the resource owner or OpenID Provider denied the request an error 403 Forbidden is sent back. Note: This is not yet available.
Request:
curl -X 'POST' \
'https://api.orange.com/openidconnect/ciba/be/v1/bc-authorize' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'scope=openid%20dpv%3AFraudPreventionAndDetection%20sim-swap%3Acheck&login_hint=tel%3A%2B32493456721&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJraWQiOiJzYW...8jK9lM0nPqRstUvwXYZ'
Response:
200
Content-Type: application/json
{
"auth_req_id": "3f7b2e8a-9cde-4f3b-8b12-1a2b3c4d5e6f",
"expires_in": 120,
"interval": 2
}
Step 2: Request the OAuth access token
Once the client application gets the authorization code, the API Invoker polls the token endpoint by making an "HTTP POST" request by sending the grant_type (urn:openid:params:grant-type:ciba), auth_req_id (OperatorAuthReqId) and the the application credentials (client_assertion & client_assertion_type) parameters
If the transaction succeeds, in the POST
response, the acccess_token
is provided.
Request:
curl -X 'POST' \
'https://api.orange.com/openidconnect/ciba/be/v1/token' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&auth_req_id=3f7b2e8a-9cde-...-1a2b3c4d5e6f&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJraWQiOiJzYW1wbGU...K9lM0nPqRstUvwXYZ'
Response:
200
Content-Type: application/json
{
"access_token": "G5kXH2wHvUra0sHlDy1iTkDJgsgUO1bN",
"token_type": "Bearer",
"refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
"expires_in": 120,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...rGvsIIwk1uExynJIv_tgZGE0eZI7MtVb2UlCwDQrVlg"
}
Step 3: Access protected resources using OAuth access token
In order to call our API, the access_token
is mandatory.
Specific documentation about SIM swap resources is provided below.
API Description
This API is based on version 1.0.0 of the API sim-swap.
Summary of resources
This API has two resources check and retrieve-date.
Summary of methods and URL
Use case of operation | URL method | required scope |
---|---|---|
I want to check if the mobile line (identified with a MSISDN) has changed sim from now -(max-age) to now. | POST https://api.orange.com/camara/obe/sim-swap/v0/check | openid dpv:FraudPreventionAndDetection sim-swap:check |
I want to get last sim swap date for a mobile line (identified with a MSISDN) | POST https://api.orange.com/camara/obe/sim-swap/v0/retrieve-date | openid dpv:FraudPreventionAndDetection sim-swap:retrieve-date |
Summary of request body parameters
Name | Description | Type | Mandatory |
---|---|---|---|
phoneNumber | Subscriber number in E.164 format (starting with country code). Optionally prefixed with '+' | string | No |
maxAge | Defines the period to be checked; This period is from now - max_age to now. If 240 is passed, server will check if a sim swap was performed on this last during last 10 days (240 hours) | integer | No |
check sim swap operation description
Checks if SIM swap has been performed during a past period (defined in the request with 'maxAge' attribute) for a given phone number.
Request
curl -X POST "https://api.orange.com/camara/obe/sim-swap/v0/check"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d '{
"phoneNumber": "+32493456721",
"maxAge": 240
}
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/sim-swap/v0/check"
...
-d '{
"maxAge": 240
}
Response
200
Content-Type: application/json
{
"swapped": false
}
Fields description
The response features only one attribute: swapped.
This attribute is a boolean indicating if a SIM swap has been done during the provided checking period.
retrieve-date sim swap operation description
Provides timestamp of latest SIM swap, if any, for a given phone number.
Request
curl -X POST "https://api.orange.com/camara/obe/sim-swap/v1/retrieve-date"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d '{
"phoneNumber": "+32493456721",
}
Response
200
Content-Type: application/json
{
"latestSimChange": "2024-09-18T07:37:53.471829447Z"
}
Fields description
The response features only one attribute: latestSimChange.
This attribute provides timestamp of latest SIM swap, if any, for a given phone number. If no SIM swap has been performed, the API will return the SIM activation date by default. If this is not possible due to local policies preventing the safekeeping of the information for longer than the stated period of time, a 'null' value will be returned.
Most frequent errors
If invalid or incomplete input are provided - in particular for the max_age (should between 1 to 2160) a 400 error is triggered.
HTTP/1.1 400 Error: bad Request
Content-Type: application/json
{
"code": "INVALID_INPUT",
"status": "400",
"message": "[checkSimSwap.createCheckSimSwap.maxAge: must be less than or equal to 2160]"
}
If the MSISDN is not managed by Orange, error code 404 is retrieved.
HTTP/1.1 404 Error: Resource Not Found
Content-Type: application/json
{
"code": "SIM_SWAP.UNKNOWN_PHONE_NUMBER",
"status": "404",
"message": "SIM Swap can't be checked because the phone number is unknown."
}
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: ..."
}
- Here, you removed your subscription to the API so that the capability to generate an access_token is not allowed anymore. As an example:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"code": "FORBIDDEN",
"message": "Operation not allowed: ..."
}
History of document
Version of the document | modification date | description of modifications |
---|---|---|
1.0 | 08/01/2025 | initialization by Orange CAMARA APIs team |
2.0 | 13/01/2025 | change access to CIBA flow |
Note: version of the document is different than version of the API.