A session object represents access to a specific source.

Sessions are always created with a pending state, until the API is able to verify access with the target source's service.

If the target source's service revokes access, the session will transition into an expired state.

Session are not client updatable.


name type description
id string Resource identifier.
resource string, always session Resource type identifier.
organisation organisation ID The organisation the session is associated with.
key key ID The key associated with this resource.
user user ID The user the session is associated with.
source nested source The source instance the session is associated with.
state string One of: pending, active, failed, expired.
error string A code referring to the reason the session expired.
date_created datetime When the resource was created.
date_expired datetime When the resource expired.


The session is still being initialised.
The session is ready to be used to submit tasks.
Session initialisation failed.
The session has been invalidated.


A session can have two types of errors: initialisation errors and expiry errors.

Session initialisation errors typically occur due to a bad username or password, the need for 2FA authentication, or the service declining access to the source for some other reason. These errors will have the init_failed error type.

Most sessions will eventually expire. More session lifetime details can be found in the service specific docs. However, there are various triggers for session expiry:

The third-party service has invalidated the session. This is typically due to session timeouts within the third-party service (i.e. a session can only last 24 hours). However, it can also be caused by the owner of the source changing their credentials, as this often invalidates existing session, or it can be triggered by a security feature within the service, such as an intruder detection system.
The API periodically invalidates inactive sessions.
The organisation has invalidated the session, possibly on behalf of the end-user.
An API administrator has invalidated the session.

Create POST /sessions


name type description
source required The source this session will be associated to. The contents should follow the source creation schema.
payload required The session initialisation payload. The required contents depend on the service the source belongs to.

Using cURL

curl \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": {
      "user": 1,
      "type": "icloud.account",
      "identifier": ""
    "payload": {
      "password": "1234"

Using ricloud-py

import ricloud

source = {
  'user': 1,
  'type': 'icloud.account',
  'identifier': '',

payload = {
  'password': '1234',

session = ricloud.Session.create(source=source, payload=payload)

Retrieve GET /sessions/{session ID}

Using cURL

curl<session ID> \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

session = ricloud.Session.retrieve(<session ID>)


GET /sessions

name type description
key key ID filter Filter by a key ID.
user user ID filter Filter by a user ID.
source source ID filter Filter by a source ID.
state string filter Filter by the session state.
date_created datetime filter Filter by when the session was created.
date_expired datetime filter Filter by when the session was expired.

Using cURL

curl \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

sessions = ricloud.Session.list()

Delete DELETE /sessions/{session ID}

This interaction expires the session and deletes any cached data associated with it on the API. The actual session resource instance is persisted for the record.

Using cURL

curl<session ID> \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

session = ricloud.Session.delete_with_id(<session ID>)

# OR

session = ricloud.Session.retrieve(<session ID>)


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 3:50 AM GMT.

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

Our awesome support team

© 2008 - 2024 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® and Camo® are registered trademarks. Privacy policy & terms.