Introduction

The Consent Info API allows API Consumers to easily validate whether they have the necessary permissions to process User's personal data for a specific Purpose before using other CAMARA APIs. It provides a simple true/false response and, when applicable, a URL to direct the User to manage their Consent.

API Scope

The current API implementation is applicable to any mass-market Orange France mobile customer, including SOSH customers.

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 to request Consent-Info, 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 Application Backend

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 ServiceProvision dpv value is managed, which means that:

• the scope in the bc-authorize must be set to openid dpv:ServiceProvision consent-info:retrieve

Request:

curl  -X POST \
  'https://api.orange.com/openidconnect/ciba/fr/v1/bc-authorize' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'login_hint=tel:+336666666' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=eyJhbGciOiJSUz...1jjGg' \
  --data-urlencode 'scope=openid dpv:ServiceProvision consent-info:retrieve'

Response:

200 
Content-Type: application/json

{
  "auth_req_id": "y_azuw2HT4fWYPb0-0w2DBhaEq8",
  "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/fr/v1/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....iuT111jjGg' \
  --data-urlencode 'auth_req_id=y_azuw2HT4fWYPb0-0w2DBhaEq8' \
  --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'

Response:

200 
Content-Type: application/json

{
  "access_token": "OFR_28Fp...Jb60y3KPvcZaOTHJ_sFnjOmyHN5PxXG...osYpKu3gA4utWicDw",
  "token_type": "Bearer",
  "refresh_token": "4bwc0ESC_IAhflf-ACC_vjD_ltc11ne-8gFPfA2Kx16",
  "expires_in": 120,
  "id_token": "OFR_28Fp...Jb60y3KPvcZaOTHJ_sFnjOmyHN5PxXG...osYpKu3gA4utWicDw"
}

Step 3: Access protected resources using OAuth access token

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

Specific documentation about consent-info/retrieve resource is provided below.

API Description

Summary of resources

This API has one resource retrieve.

Summary of methods and URL

Summary of request body parameters

In bold parameters currently available in Orange France API

Summary of response parameters

Details on statusInfo:

Explanation on **statusReason **values:

• PENDING: The requested data processing has not yet been established or fully validated under the applicable privacy regulations. For example, the User has not yet provided Consent when it is required.
• REQUESTED: The permission for the requested data processing has been submitted but has not yet been granted or confirmed. This is common when the API Consumer has initiated a request for Consent capture, but the User has not yet completed the process. For example, this occurs when a notice prompting the User to provide Consent has been displayed, but they have not yet made a decision.
• REVOKED: The User has actively withdrawn their permission for the requested data processing after previously opting in. For example, the User revokes their Consent for the data processing.
• OBJECTED: The user has opted out of the requested data processing, despite a previous explicit opt-in not being required. This is common when the User has exercised their right to object to data processing under the applicable privacy regulations.
• EXPIRED: When applicable, the validity of the data processing has ceased due to the passage of time or a pre-defined condition. This is common for time-limited Consents.

Request

curl -X POST "https://api.orange.com/camara/ofr/consent-info/v0.1/retrieve"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
  "phoneNumber": "+123456789",
  "scopes": [
    "location-verification:verify"
  ],
  "purpose": "dpv:FraudPreventionAndDetection",
  "requestCaptureUrl": true
}'

Response examples

Case 1: Ready For processing:

200 OK
Content-Type: application/json

{
  "statusInfo": [
    {
      "scopes": [
        "number-verification:verify"
      ],
      "purpose": "dpv:FraudPreventionAndDetection",
      "statusValidForProcessing": true
    }
  ]
}

Case 2: Consent in required and capture url was not requested:

200 OK
Content-Type: application/json

{
  "statusInfo": [
    {
      "scopes": [
        "location-verification:verify"
      ],
      "purpose": "dpv:FraudPreventionAndDetection",
      "statusValidForProcessing": false,
      "statusReason": "REQUESTED"
    }
  ]
}

Case 3: Consent in required and capture url was requested:

in this example an existing consent was granted but was expired.

200 OK
Content-Type: application/json

{
  "statusInfo": [
    {
      "scopes": [
        "location-verification:verify"
      ],
      "purpose": "dpv:FraudPreventionAndDetection",
      "statusValidForProcessing": false,
      "statusReason": "EXPIRED",
      "expirationDate": "2023-07-03T14:27:08.312+02:00"
    }
  ],
  "captureUrl": "https://example.org/consent-capture-url"
}

Case 4: Consent is revoked:

Valid case when explicit consent is the legal base.

200 OK
Content-Type: application/json

{
  "statusInfo": [
    {
      "scopes": [
        "location-verification:verify"
      ],
      "purpose": "dpv:FraudPreventionAndDetection",
      "statusValidForProcessing": false,
      "statusReason": "REVOKED"
    }
  ]
}

Case 5: Consent is objected:

Valid case when legitimate interest is the legal base.

200 OK
Content-Type: application/json

{
  "statusInfo": [
    {
      "scopes": [
        "location-verification:verify"
      ],
      "purpose": "dpv:FraudPreventionAndDetection",
      "statusValidForProcessing": false,
      "statusReason": "OBJECTED"
    }
  ]
}

Most frequent errors

If invalid input are provided in particular for the device identifier a 400 error is triggered.

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "code": "INVALID_ARGUMENT",
  "status": 400,
  "message": "Client specified an invalid argument, request body or query param."
}

If the client provided a phone number within the access token but also provide it in the API payload an error 422 is end back.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json
{
  "status": 422,
  "code": "UNNECESSARY_IDENTIFIER",
  "message": "The phone number is already identified by the access token."
}

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": "UNAUTHENTICATED",
  "status": 401,
  "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": "PERMISSION_DENIED",
  "status": 403,
  "message": "Operation not allowed: ..."
}