Getting started

Updated

To start using the ricloud v3 API, you first need to get in touch to setup your organisation. Once this is completed, you should have your initial key_token which will grant you access to the API.

The API calls in this section are performed using cURL, but these can be easily substituted with equivalent calls from ricloud-py.

Viewing your organisation

First, we will take a quick look at your organisation.

curl 'https://ricloud-api.reincubate.com/organisation' \
  -H 'Authorization: Token <your key_token>'

You should see a response similar to the one below. If you get a HTTP 401 response then check the key_token value you supplied in the Authorization header.

{
    "id": 1,
    "resource": "organisation",
    "name": "Getting started",
    "slug": "getting-started",
    "permissions": {
        "id": 1,
        "resource": "organisation_permissions",
        "identifier": "default",
        "scopes": {
            "source_type:icloud.*": [],
            "task_type:*": [],
            "data_type:icloud.account.info": [],
        },
        "date_created": "2018-11-22T12:59:57.168354Z"
    },
    "storage_configs": [],
    "storage_config_default": null,
    "webhook_configs": [],
    "webhook_config_default": null,
    "state": "unconfigured",
    "date_created": "2018-11-22T12:59:57.016467Z"
}

Here you can see some information about your organisation:

  • permissions displays the base permissions for your organisation.
  • storage_configs and storage_config_default are empty as we are yet to setup any.
  • webhook_configs and webhook_config_default are also empty for the same reason.
  • state is unconfigured which reflects the lack of valid storage configs.

We will come back to configuration steps later, as this does not prevent you from accessing services through the API.

Now that we have confirmed your organisation is up and running, let's try accessing an iCloud account.

Setting up a session

A session represents access to a source. In the case of an iCloud account source, the API will need to log into the account to create the session between itself and the Apple's iCloud service.

Create a user

Before a session can be setup, a user needs to be created to define which end-user wants to access the source. This helps with session management and data security on the API.

curl 'https://ricloud-api.reincubate.com/users' \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "identifier": "<some identifier for the user your system will recognise>",
}'

The response will contain the user ID needed in the next call.

{
  "id": "1",
  "resource": "user",
  "organisation": "1",
  "key": "1",
  "identifier": "<your user identifier>",
  "state": "active",
  "date_created": "2018-11-22T13:49:37.215516Z"
}

Create a session

curl 'https://ricloud-api.reincubate.com/sessions' \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "source": {
    "user": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
  }
}'

The response will contain a session resource, which will initially be in the pending state while the API goes through the process of setting up communications with the third-party service. In this case, we are getting getting access to the iCloud.

{
  "id": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "resource": "session",
  "organisation": "1",
  "user": "1",
  "source": "1",
  "state": "pending",
  "error": null,
  "date_created": "2018-11-22T13:50:12.628776Z",
  "date_expired": null
}

You can check the state of the session via the retrieve call.

curl 'https://ricloud-api.reincubate.com/sessions/ed855b07-f72b-4983-ac1d-980fafee8a0b' \
  -H 'Authorization: Token <your key_token>'

If the state becomes failed, something went wrong during the initialisation process. Check the value of the error attribute for more detail on what went wrong.

In the case where 2FA is enabled on your account, the error encountered is very likely to be code-required and you will have been prompted with the 2FA process on one of your devices. Simply make the call from step (1) again, but this time including the 2FA code in the payload.

curl 'https://ricloud-api.reincubate.com/sessions' \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "source": {
    "user": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
    "code": "<2FA code>"
  }
}'

If another error occurred, please check the errors section for more details.

Once the state becomes active the session is ready for use to retrieve data and files from the source. However, as we saw earlier, your organisation is not yet configured to receive any of this data, bringing us to the next step.

Retrieving data and files

Before the API can start fetching data from a source, it needs to know where it should publish the data to. The API currently supports publishing to Google Cloud Storage and Amazon S3 (AWS) storage buckets, which need to be configured through a storage config belonging to your organisation. Follow the steps outlined in the storage configuration setup docs to get a bucket of your own ready for use with the API.

Create a poll for data

The simplest set of data to retrieve from the iCloud is some basic account information. All that is needed is the ID of an active session and some specifiers for the data you are looking to recover.

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "type": "data",
  "payload": {
    "data_types": ["callkit.calls"],
  }
}'

Note the in the call above we specified the callkit.calls data type, but your key might have permissions for different data types or you might be interested in retrieving a different kind of data, just substitute as necessary.

This will return a poll resource. In the background, the API has also created a task which will do the actual work required to retrieve this information (a task was also created to set up our session earlier). The ID of the task can be seen under the tasks attribute.

{
  "id": "f1447e76-59f1-486b-942f-6b90e3570c63",
  "resource": "poll",
  "organisation": "1",
  "key": "1",
  "user": "1",
  "source": "1",
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "type": "data",
  "tasks_pending": [],
  "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "tasks_completed": [],
  "results": [],
  "state": "processing",
  "date_created": "2018-11-22T14:20:52.211618Z",
  "date_started": "2018-11-22T14:20:52.731838Z",
  "date_completed": null
}

Also note the results attribute, which is empty at this point. This is where we will start seeing the IDs of data published from the task.

Now, we want to wait until processing is complete and the poll's state is set to succeeded.

Retrieve result information

This is easily done by looking at the results attribute of the poll.

curl 'https://ricloud-api.reincubate.com/polls/f1447e76-59f1-486b-942f-6b90e3570c63' \
  -H 'Authorization: Token <your key_token>'

The response will contain the information we need.

{
  "id": "f1447e76-59f1-486b-942f-6b90e3570c63",
  "resource": "poll",
  "organisation": "1",
  "key": "1",
  "user": "1",
  "source": "1",
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "type": "data",
  "tasks_pending": [],
  "tasks_processing": [],
  "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "results": [
    {
      "id": "754cfef0-7576-44c0-acfe-8b0d8d0dd32f",
      "resource": "result",
      "task": "6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb",
      "identifier": "data:info.account",
      "url": "<your storage config url>",
      "checksum": "2668324d21a20301ce71c28bc5e621d4",
      "size": 12345,
      "state": "available",
      "date_created": "2018-11-22T14:20:53.506542Z",
      "date_consumed": null,
      "date_deleted": null
    }
  ],
  "state": "processing",
  "date_created": "2018-11-22T14:20:52.211618Z",
  "date_started": "2018-11-22T14:20:52.731838Z",
  "date_completed": "2018-11-22T14:20:53.548372Z"
}

The result's url attribute will point to the file stored in your bucket.

Receiving webhook events

Certain API functionality is triggered automatically, either as a result of external triggers such as an asrelay instance finding new data or due to a scheduled poll. In these cases, the API needs a way to tell your system that changes have happened or that new data has been published which you should be aware of.

To do this, the API makes use of webhook notifications. Before the API can start sending these, and before you can start using the asrelay service or scheduled polls, your organisation needs to be configured with a valid webhook config. Follow the guide on webhook configuration for more details.

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9 AM to 5 PM GMT. The time is currently 7:02 AM GMT.

We aim to reply to all messages within one working day.

Go to support section › Contact the enterprise team ›
Our awesome support team

Can we improve this article?

We love hearing from users: why not drop us an email, leave a comment, or tweet @reincubate?

© 2008 - 2019 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® is a registered trademark. Privacy & terms. We recommend 2FA. Built with in London.