.wpb_animate_when_almost_visible { opacity: 1; }
Cloud France
Enrich your service with Orange Cloud, the personal online storage service available to our mobile & broadband customers. Access, upload and manage content.
1.5
API deprecated

This document describes each steps of the whole process to access user data (folders, files) stored on the Orange Cloud, through the Orange Cloud API.

If you are not an Orange France customer you will need a testing account to check your API integration is operational. You can request a testing account in our Support section, just complete the 'Contact us' form and select the appropriate topic. We will handle your request within 2 business days.

Terminology:

  • client: your application that will make Orange API calls
  • user: the customer who will use your application
  • endpoint: the url to access, in REST, to a function of the API
  • header: a user defined HTTP header used to carry information in a REST call

Use cases:



Before starting

In order to be able to make calls to the Orange Cloud API, you need credentials for your application. To get these credentials, you need to create an account and register your application on the Orange Developer Portal.

Here are the steps of this registration process :

  • Log in / create an account on Orange Developer (if you have an Orange Partner account you can use the same login credentials)
  • Validate your email (if you're creating a new account)
  • Go to 'My Apps' and register an app
  • Click 'Add API' and select 'Cloud France'

At the end of this registration process, you will be provided with :

  • client identifier: a unique ID provided by the Orange backend server to identify your application
  • client secret: it is used to get a token for initial access.

  • How to integrate the Cloud API ? Check out the webinar.

User authentication

Orange will need to verify the identity of your users and let them grant you permission to access their private data on Orange-Cloud.

For this purpose, Orange uses “3-Legged OAth 2”. Once authentication completed by your user, Orange will return a String-code “Access-Token”.

Your application must send this String-code with each API-query it will make on Orange-Cloud.

Orange uses this String-code to uniquely identify both your app and the end user.

Below a diagram explaining the process flowed by Orange to authorize your app access to user’s Cloud-data :

Imagine an Orange user (David) wants to Download his photos using your App : “My-App”

enter image description here

So let start and get the Authorization code : The first step is to ask the end user to authenticate to his/her Cloud. Depending on your permissions, use the appropriate scope.

ScopeDescription
openidRequests an ID token and retrieves User identifier for SSO.
cloudGrants read and write access to user's Cloud. Access is limited to the application's folder.
cloudfullreadGrants read access to user's Cloud. Access is extended to the whole Cloud.
cloudfullwriteGrants write access to user's Cloud. This privilege must be used with cloudfullread to be active. Access is extended to the whole Cloud. This scope is restricted. To get further information, please fill in this form (requires you to sign-in first or sign-up) and we will be contacting you shortly.
https://api.orange.com/openidconnect/fr/v1/authorize?
scope=openid%20cloud
&response_type=code
&client_id=6KRHymujFP8...Ee6a8SG2g
&state=state
&redirect_uri=http%3A%2F%2Fwww.myorangecloudapp.com

Remember that you need to specify the client_id and redirect_uri values you got during the registration process. For security reasons, you can only use the value specified during the registration process for the redirect_uri parameter. Note the special encoding for redirect_uri value: it must be url encoded (e.g. "://" has to be replaced by "%3A%2F%2F")

This URL displays a web page that takes care about authenticating the user and getting his/her consent for using the service. Once this is done, the redirect URL is automatically called back with an authorization code:

http://www.myorangecloudapp.com/?code=OFR-251f7...716a727f&state=state

Getting the token

You can now use this authorization code to retrieve an access token that will be used for all further API calls. To get this token, you have to use a POST method with the endpoint /oauth/v2/token :

curl -X POST \
     -H "Authorization: Basic NktSSHl...UdnlrT2lOaA==" \
     -d "grant_type=authorization_code \ &code=OFR-251f7...716a727f \
     &redirect_uri=http://www.myorangecloudapp.com" \
     https://api.orange.com/openidconnect/fr/v1/token

In the body data of the request, be sure to use the authorization code you just get and do not forget to set again the redirect_uri.

In addition you need to specify the ‘Authorization’ HTTP header. To find your Authorization header, login, ‘go to My apps’, select your application, and click on ‘show’ in your app details summary page.

The Authorization header is formed like this :

"Basic "+base64encode("client_id+":"+client_secret")

If this POST request succeeded, you should receive JSON data, similar to :

{
 "token_type":"Bearer",
 "access_token": "OFR-948ef...d5de1f4",
 "expires_in":3600,
 "scope":"openid cloud",
 "refresh_token": "OFR-fa78dfb0dcf01…ff5c", 
 "id_token": "eyJ0eX9….xCN7KiBNYiSAPd0XEs" 
}

Congratulations! You just got the token you have to use from now to all subsequent API calls. It is stored in the value associated with the name access_token. It is valid for the duration, in seconds, specified by expires_in.

This access token can be renewed thanks to the refresh token. It's recommended to renew it before the expiration time.

To renew the access token, your app should execute the same /token request with the same header. The only change is the value of grant_type paramter that must be "refresh_token" and refresh_token parameter that must be the value of the refresh token previously received.

curl -X POST 
     -H "Authorization: Basic MGtBU0XPtr.."
     -d "grant_type=refresh_token&refresh_token=OFR-3d97599b955b..." 
      https://api.orange.com/openidconnect/fr/v1/token

Privileges and root folder

There are two types of privileges :

  • Your application is entitled by default the right to access all the user contents in read mode. To be able to write contents, your application can do so in a dedicated folder created within the Cloud of the end-user the first time your application uploads a file. For instance, if your application is named "MyBeautifulApp", you have only rights inside the folder "mes dossiers partenaires/MyBeautifulApp". Your application will have the full freedom to create directories, manipulate files and folders, upload, download, delete, within this folder.
  • The Cloud Full Access API provides full access to the entire Cloud of the end-user. Your application will be able to read and write content everywhere in the user's folders and files.

Getting and Listing your "root" folder

Your API rights determine your application's default root directory. If your application is not entitled with full access permissions, you will probably need to determine your application's specific folder. Use the parameter restrictedmode to point directly to your application specific folder.

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     https://api.orange.com/cloud/v1/folders/restrictedmode

This request returns JSON data containing information about your root folder, as well as two sub arrays, one for the files (files) and one for the folders (subfolders). Note that an id is the file path encoded in base64, and thus can be conveniently used for debugging purposes.

{
 "id": "VHlwZSAob3IgcGFzdGUpIGhlcmUuLi4=",
 "parentId": "Lw==",
 "name": "MyBeautifulApp",
 "files":
 [{
  "id": "dmlkZW9EZWZhdWx0Lm1wNA==",
  "name": "videoDefault.mp4",
  "type": "VIDEO"
  },
  { "id": "cGRmRGVmYXV0LnBkZg==",
    "name": "pdfDefaut.pdf",
    "type": "FILE"
  },
  {
    "id": "aW1hZ2VEZWZhdXQyLmpwZw==",
    "name": "imageDefaut2.jpg",
    "type": "PICTURE"
  }],
 "subfolders":
  [{
  "id": "X191cGxvYWQv",
  "name": "__upload"
 }] 
}

Listing a specific subfolder

Listing a subdirectory is really similar, you just need to make the same call as for the root folder, with the same endpoint (/cloud/v1/folders/), appending the folder identifier (the "id" field in the returned JSON) that you want to be listed:

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     "https://api.orange.com/cloud/v1/folders/X191cGxvYWQv"

The returned information has exactly the same structure as the one returned by the root folder listing call. This way you can easily browse recursively your directory hierarchy.

Listing only subfolders

To list only subfolders , use the optional parameter tree:

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     "https://api.orange.com/cloud/v1/folders?tree=true"

Listing only subfolders recursively

To list only subfolders and recursively, use the optional parameter tree combined to the parameter flat :

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     "https://api.orange.com/cloud/v1/folders?tree=true&flat=true"

Listing all contents recursively

To list all subfolders and files recursively, use the optional parameterflat. Note that this request might be heavy and it depends on the numbers of files of the end user.

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     "https://api.orange.com/cloud/v1/folders?flat=true"

Filtering on photos, videos, audio files

To get all photos, videos or audio files in a folder and its subfolders, use the optional parameter filter to select the type of content and flat to list recursively.

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     "https://api.orange.com/cloud/v1/folders?filter=image&flat=true"

For audio files use the filter audio and for video files use video.

This request will also return all subfolders.

Getting all photos with thumbnails

While listing all the photos, use the optional parameter showthumbnailsto include the thumbnails. This parameter takes no value

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     "https://api.orange.com/cloud/v1/folders?filter=image&flat=true&showthumbnails"

Pagination

If your application requires to get a limited number of content then the pagination could help. For example, your application needs to get all photos on the cloud but display only 10 photos per page. Use the parameter limit and offset :

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     "https://api.orange.com/cloud/v1/folders?flat=true&filter=image&limit=10&offset=10"

Continue incrementing the offset by 10 until you reach a response with no item.

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     "https://api.orange.com/cloud/v1/folders?flat=true&filter=image&limit=10&offset=20"

Getting more info

Once you have a list of files, you can get more information about a particular file with the /cloud/v1/files/{file_id} URI using the file identifier.

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     https://api.orange.com/cloud/v1/files/aW1hZ2VEZWZhdXQyLmpwZw==

This request also returns JSON data containing additional information:

  • id : id of the file
  • name: name of the file
  • size: the file size in bytes
  • type: the file type among FILE, PICTURE, VIDEO and AUDIO
  • creationDate: the time the file has been uploaded
  • thumbUrl: a URL to get a thumbnail representation of the content, if any
  • downloadUrl: a URL to download the file content.
  • previwUrl: a Url to preview the file
  • lastUpdateDate:
  • metadata: related to the file type. Ot could be height and width of a photo, cover, album name or duration for an audio file, and height, width or duration for a video file
{
"id":"eWVuZ2xpc2gvY2xvdWRzeW5jLnBuZw",
"name":"cloudsync.png",
"type":"PICTURE",
"thumbUrl":"https://cloudapi.orange.com/cloud/v1/files/eWVuZ2xpc2gvY2xvdWRzeW5jLnBuZw/thumb/aHR0cHM6Ly9kb3dubG9hZGluZ",
"previewUrl":"https://cloudapi.orange.com/cloud/v1/files/eWVuZ2xpc2gvY2xvdWRzeW5jLnBuZw/preview/aHR0cHM6Ly9kb3dB",
"metadata":{"height":133,"width":174},
"lastUpdateDate":"2016-02-15T08:30:17+0100",
"creationDate":"2016-02-15T08:30:16+0100",
"size":29319,
"downloadUrl":"https://cloudapi.orange.com/cloud/v1/files/eWVuZ2xpc2gvY2xvdWRzeW5jLnBuZw/content/aHR0cHMlsZQ"}
}

Downloading a file

Now you can download the file with a simple GET request once you've got the file id from list files and folders response. Note also that the authority is different(i.e. cloudapi.orange.com instead of api.orange.com).

curl -X GET \
     -H "Authorization: Bearer OFR-948ef5..." \
     https://cloudapi.orange.com/cloud/v1/files/aW1hZ2VEZWZhdXQyLmpwZw==/content/aHR0cHM6L...RmlsZQ==

Getting available space

To get the remaining space available for storage, you have to make a GET request with the /freespace URI with usual headers :

curl -X GET -H "Authorization: Bearer OFR-948ef5..."
     https://api.orange.com/cloud/v1/freespace

The call will return JSON data containing a single field with the available free space:

{ "freespace": 53597116521 }

Note that the size is in bytes and thus should be handled with a long integer to deal with numbers greater than giga bytes.

Uploading a file

To use the simple upload, you have to make a POST request with /files/content URI specifying the identifier of the target folder where the file will be uploaded. You get this information after listing folders.

curl -X POST 
     -H "Content-Type: image/jpeg" 
     -H "Authorization: Bearer OFR-948ef5..." 
     --data-binary "@test.jpeg" 
     -L "https://cloudapi.orange.com/cloud/v1/files/content?name=test.jpeg&folder=Lw"

Note: the max file size is 4Gb.

File operations

There are a number of operations for files and folders. You can perform copy, rename, move and delete files and folders and also create folders. These operations are basically performed with an HTTP POST method using the folder or the file identifier.

Warning : Note that every operation has to be executed unitary and cannot be combined with another operation in the same request. For instance, you cannot perform copy and rename in the one request. An error message with HTTP 400 Bad Request status code will be returned.

Copy a file

To copy a file, you have to make a POST request with /files/{file_id} URI specifying the file identifier and the destination folder identifier and the parameter clone which value is equal to true.

curl -X POST \ 
     -H "Authorization: Bearer OFR-948ef5..." 
     -H "Content-Type: application/json" \
     -d "{\"parentFolderId\":\"Lw\", \"clone\":\"true\"}" \
     https://api.orange.com/cloud/v1/files/bWVzz

Copy a folder

To copy a folder, you have to make a POST request with /folders/{folder_id} URI specifying the source and destination folder identifiers in the request body. You have to put the identifier of the source folder that you want to copy in the URL and the identifier of the destination folder as the value of the JSON parameter parentFolderId. You also need to set the parameter clone value to true.

curl -X POST \ 
     -H "Authorization: Bearer OFR-948ef5..." 
     -H "Content-Type: application/json" \
     -d "{\"parentFolderId\":\"Lw\", \"clone\":\"true\"}" \
     https://api.orange.com/cloud/v1/folders/bWVrtyxz

If the request succeeded, you should receive a response with 201 Created HTTP status code and the URI of the copied file (see Content-Location HTTP header).

Rename a file

To rename a file, you have to make a POST request with /files/{file_id} URI using the file identifier with usual headers:

curl -X POST \ 
     -H "Authorization: Bearer OFR-948ef5..." 
     -H "Content-Type: application/json" \
     -d "{\"name\":\"myLoveSong.mp3\"}" \
     https://api.orange.com/cloud/v1/files/X191cMw

Rename a folder

To rename a folder, you have to make a POST request with /folders/{folder_id} URI using the folder identifier and the new name for the folder.

curl -X POST \ 
     -H "Authorization: Bearer OFR-948ef5..." 
     -H "Content-Type: application/json" \
     -d "{\"name\":\"level2.2.Rename\"}" \
     https://api.orange.com/cloud/v1/folders/4yLw

Move a file

To move a folder, you have to make a POST request with /folders/{folder_id} URI specifying the source and destination folder identifiers in the request body. The only difference with a copy file operation is the value of parameter clone that is equal to false here.

Note that the only difference with the copy operation if the value of the json parameter clones that takes the value false in this case.

curl -X POST \ 
     -H "Authorization: Bearer OFR-948ef5..." 
     -H "Content-Type: application/json" \
     -d "{\"parentFolderId\":\"Lw\", \"clone\":\"false\"}" \
     https://api.orange.com/cloud/v1/files/bWVzz

Move a folder

To move a folder, you have to make a POST request with /folders/{folder_id} URI specifying the source and destination folder identifiers in the request body. The only difference with a copy folder operation is the value of parameter clone that is equal to false here.

Note that the only difference with the copy operation if the value of the json parameter clones that takes the value false in this case.

curl -X POST \ 
     -H "Authorization: Bearer OFR-948ef5..." 
     -H "Content-Type: application/json" \
     -d "{\"parentFolderId\":\"Lw\", \"clone\":\"false\"}" \
     https://api.orange.com/cloud/v1/folders/bWVrtyxz

Creating a folder

In order to create a new directory, you have to make a POST request with /folders URI specifying the name of the new directory and its parent folder as JSON data in the request body. Don't forget to set a HTTP header for the JSON content type (Content-Type: application/json):

curl -X POST \ 
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OFR-948ef5..." \
     -d "{\"name\":\"myNewDir\", \"parentFolderId\":\"Lw\"}" \
     https://api.orange.com/cloud/v1/folders

If the request succeeded, you should receive JSON data that basically contains the result of a folder listing of the newly created directory

{
 "id" = "bXlOZXdEaXIv";
 "name" = "myNewDir";
 "parentId" = "Lw==";
 "files" = ();
 "subfolders" = ( );
}

Deleting a file

To delete a file, you have to make a DELETE request with the files/{file_id} URI, using the file identifier and usual headers:

curl -X DELETE
     -H "Authorization: Bearer OFR-948ef5..."
     https://api.orange.com/cloud/v1/files/bXlvcmFuZ2VjbG91ZGFwcC9JTUdfMDAwNCgxKS5KUEc=

The call will return nothing but either a HTTP 204 on success or any relevant error code.

Deleting a folder

Deleting a folder is really similar to deleting a file, you also have to make a DELETE request with the folders/{folder_id} URI using the folder identifier and usual headers:

curl -X DELETE
     -H "Authorization: Bearer OFR-948ef5..."
     https://api.orange.com/cloud/v1/folders/bXlvcmFuZ2VjbG91ZGFwcC90b3RvLw==

The call will return nothing but either a HTTP 204 on success or any relevant error code.

Warning: all files and subfolders contained inside the folder to be deleted will be deleted as well.

Exception management

Errors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call, JSON-formatted. Error codes not listed here are in the API methods listed below.

Here is a list of the main errors specific to cloud requests. They follow the generic error format (code / message / description). Note that the message can have a prefix, which is represented with a "*" character in the list below.

CodeMessageDescription & Expected behaviour
400*MISSING_PARAMETERA mandatory input is missing (refer to error details). The partner should enrich the request and retry.
400*INVALID_PARAMETERA mandatory input is invalid (refer to error details). The partner should check the request and retry.
401*INVALID_CLIENTThe requested service needs credentials, and the ones provided were out-of-date, you need to refresh the token
401*INVALID_CLIENTThe requested service needs credentials, but the ones provided were invalid
403*FORBIDDEN_ACCESSThe validated scope does not authorize the partner to request the resource. The partner should ask the end user for their consent.
403PDK_*-USER_NOT_ELIGIBLEThe end user is not eligible to the Cloud service. The partner should inform the user and may redirect them to the service landing page. Use the following message: - English: You do not have an Orange Cloud. For further information, please connect to the Orange Cloud website. - French: Vous n'avez pas de Cloud Orange. Pour plus d'informations, veuillez-vous connecter au site du Cloud Orange
403PDKCW*-CGU_NOT_ACCEPTEDThe end user should accept the ToU prior to accessing the Cloud service. The user should be redirected to the service landing page. Use the following message: - English: To connect to your Orange Cloud, thanks to first validate the service Terms & Conditions. - French: Pour vous connecter à votre Cloud Orange, vous devez au préalable valider les Conditions Générales d'Utilisation du service
403*TOO MANY REQUESTSThe application has made too many calls and has exceeded the rate limit for this service.
500*SESSION_EXPIREDCurrent session has expired. The partner should init a new session by calling the "Init session" method.
500*INTERNAL_ERRORInternal error. The partner may retry the request. If the retry fails, the partner should contact the support.
503*INTERNAL_ERRORInternal error. The partner may retry the request. If the retry fails, the partner should contact the support.
501*UNSUPPORTED_COUNTRYCountry not supported. The partner should inform the end user that the service is not available yet.