Sessions

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.

Attributes

States

pending

The session is still being initialised.

active

The session is ready to be used to submit tasks.

failed

Session initialisation failed.

expired

The session has been invalidated.

Errors

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:

service

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.

api

The API periodically invalidates inactive sessions.

organisation

The organisation has invalidated the session, possibly on behalf of the end-user.

admin

An API administrator has invalidated the session.

Create POST /sessions

Parameters

Using cURL

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": "john.appleseed@reincubate.com"
    },
    "payload": {
      "password": "1234"
    }
}'

Using ricloud-py

import ricloud

source = {
  'user': 1,
  'type': 'icloud.account',
  'identifier': 'john.appleseed@reincubate.com',
}

payload = {
  'password': '1234',
}

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

Retrieve GET /sessions/{session ID}

Using cURL

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

Using ricloud-py

import ricloud

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

List

GET /sessions

Using cURL

curl https://ricloud-api.reincubate.com/sessions \
  -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 https://ricloud-api.reincubate.com/sessions/<session ID> \
  -X DELETE \
  -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>)

session.delete()