Organisations
The organisation resource helps link together all other API resources that relate to a client of the API (here a client is an API customer, not an API client implementation).
An organisation must be configured before its API keys can be used to perform data retrieval operations against the API. Without at least a valid storage configuration the API won't know how to publish results.
An organisation keeps track of a set of base permissions. These describe what operations keys within the organisation are allowed to perform against the API.
Attributes
| name | type | description |
|---|---|---|
id |
organisation ID | Resource identifier. |
resource |
string, always organisation |
Resource type specifier. |
type |
super, string | One of: standard, super. |
name |
string | The chosen name for the organisation. |
slug |
string | The slugified version of name. |
api_version |
API version | The API version the organisation is configured to use. |
config |
nested object | Organisation-wide configuration settings. |
permissions |
permissions resource | Nested permissions resource. |
storage_configs |
list object containing storage config resources | Nested list of storage config objects associated with the organisation. |
storage_config_default |
optional, storage config ID | The ID of the organisation's default storage config. |
webhook_configs |
list object containing webhook config resources | Nested list of webhook config objects associated with the organisation. |
webhook_config_default |
optional, webhook config ID | The ID of the organisation's default webhook config. |
state |
string | One of: unconfigured, active, deactivated, blocked. |
date_created |
datetime | When the resource was created. |
Types
standard- For clients of the API.
super- For internal managers of the API.
Configuration
Organisation-level configuration can be set on the config attribute of the organisation. For the moment, this only accepts publish_source_files, related to the source file publishing mechanism.
Permissions
The permissions value specifies the set of base permissions for the organisation. These are the least strict permissions afforded to any sub-resource of that organisation, i.e. a key or a user cannot have access to more data than the organisation it belongs to.
States
unconfigured- Every organisation is created in this state. Being in this state blocks access to most data-retrieval functionality.
active- The organisation has been configured and can use all parts of the API.
deactivated- The organisation has been shut-down on request of the owner.
blocked- The organisation has been shut-down by an API administrator.
Changelog
2020-02-20
- Major The
storage_configsandwebhook_configsattributes of the organisation object are now a nested list object, rather than a simple list attribute.
Retrieve GET /organisation
Using cURL
curl https://ricloud-api.reincubate.com/organisation \ -H 'Authorization: Token <your key_token>'
Using ricloud-py
import ricloud ricloud.Organisation.retrieve()
Sample response
{ "id": 1, "resource": "organisation", "name": "My org", "slug": "my-org", "api_version": "2020-02-20", "permissions": { "id": 1, "resource": "organisation_permissions", "identifier": "default", "scopes": { "source_type:icloud.*": [], "task_type:*": [], "data_type:icloud.account.info": [], }, "date_created": "2018-11-08T13:05:29.954188Z" }, "storage_configs": { "data": [ { "id": 1, "resource": "storage_config", "type": "gs", "url": "gs://my-storage-bucket", "credentials": {}, "state": "valid", "date_created": "2018-11-08T16:47:56.849618Z" } ], "has_more": false, "total_count": 1, "url": "/configs/storage" }, "storage_config_default": 1, "webhook_configs": { "data": [ { "id": 1, "resource": "webhook_config", "url": "https://www.mywebhookendpoint.com/webhooks", "secret": "Wg69dQaffJuXckXsdoHuPYkf3VSWEGMa", "state": "valid", "date_created": "2018-11-08T13:07:59.563975Z" } ], "has_more": false, "total_count": 1, "url": "/configs/webhook" }, "webhook_config_default": 1, "state": "active", "date_created": "2018-11-08T13:05:29.784270Z" }
Update POST /organisation
Parameters
| name | type | description |
|---|---|---|
name |
string | Change the display name of your organisation. |
storage_config_default |
storage config ID | Change the default storage config used by your organisation. |
webhook_config_default |
webhook config ID | Change the default webhook config used by your organisation. |
Using cURL
curl 'https://ricloud-api.reincubate.com/organisation' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "name": "My new organisation name" }'
Using ricloud-py
import ricloud ricloud.Organisation.update(name='My new org')
Sample response. Note that the slug attribute does not change, as it is only generated on initial organisation creation.
{ "id": 1, "resource": "organisation", "name": "My new org", "slug": "my-org", "permissions": {}, "storage_configs": { "data": [ { "id": 1, "resource": "storage_config", "type": "gs", "url": "gs://my-storage-bucket", "credentials": {}, "state": "valid", "date_created": "2018-11-08T16:47:56.849618Z" } ], "has_more": false, "total_count": 1, "url": "/configs/storage" }, "storage_config_default": 1, "webhook_configs": { "data": [ { "id": 1, "resource": "webhook_config", "url": "https://www.mywebhookendpoint.com/webhooks", "secret": "Wg69dQaffJuXckXsdoHuPYkf3VSWEGMa", "state": "valid", "date_created": "2018-11-08T13:07:59.563975Z" } ], "has_more": false, "total_count": 1, "url": "/configs/webhook" }, "webhook_config_default": 1, "state": "active", "date_created": "2018-11-08T13:05:29.784270Z" }
