Table of Contents

• Prerequisite authentication
• Base URL
• Resources
• Errors

Prerequisite authentication

Access to this API is secured by the OAuth 2.0 framework with the Client Credentials grant type, which means that you will have to present an OAuth 2.0 access_token whenever you want to request this API.

It's easy to negotiate this access_token: just send a request to the proper token negotiation endpoint, with a Basic Authentication header valued with your own client_id and client_secret.

For this API, the token negotiation endpoint is:

https://api.orange.com/oauth/v3/token

A technical guide is available to learn how to negotiate and manage these access_token.

Important

• Please pay particular attention to properly handle authentication error responses in your application. See the section Errors
• The access_token default lifetime is 60 minutes.
• Header Accept: application/json is now required, when it’s omitted you will receive an error 406 error.

Base URL

The Base URL is the first part of the full invocation URL, just before the resource paths. Whenever you make requests on this API, you will need to prepend the following Base URL to the resource paths defined for this API.

If you request this API and encounter a 404 NOT FOUND HTTP error response, please check first that the Base URL is correct.

The Base URL for this API is:

https://api.orange.com/cri_dev/v1/

Resources

Here is some information describing how to use the API (if provided by the API owner).

Errors

Important

Failure to code a proper management of the error responses in your application may affect its resilience. Access to the API may be revoked if your application generates too many mishandled errors.

Your application must parse the returned HTTP response to check if an error is returned instead of a 200 OK. Orange APIs use appropriate HTTP status codes to indicate any request processing error, providing detailed information about the underlying fault. This helps you provide better feedback to your users and implement failure recovery mechanism in your application.

For details on the main error codes, response format, tips and troubleshooting, see our Handling API errors guide. Here are the most common client errors encountered.

Errors 401

If you get a status code 401 with the error code 42 (such as below), then request a new access_token.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": 42,
  "message": "Expired credentials",
  "description": "The requested service needs credentials, and the ones provided were out-of-date."
}

Important

• Each access_token has a lifetime validity period (60 minutes by default). This validity period may change overtime to comply with security rules.
• Token requests are limited to 50 requests per minutes, when the rate limit is exceeded you will receive an error 429. Therefore, DON'T request an access_token each time you invoke the service API. DON'T hard-code a validity duration in your application. Instead, your application must parse the returned status code and error code to check if it needs to request a new access_token.

For other 401 errors: check that you provide the right Autorization header with the right Bearer.

Errors 400

In case of invalid request to the API, you will receive a 400 error code with detailed information in the body message, such as:

HTTP/1.1 400 Bad Request
{
  "code": 25,
  "description": "Missing header",
  "message": "...."
}

Consult all generic errors.