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
| 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. |
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
| 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 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
| 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 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()