Keys

Updated

A key gives access to the API at the organisation level via its token attribute. It is allowed to interact with all API endpoints on behalf of its organisation.

A key is generated for each newly created organisation.

Attributes

name type description
id key ID Resource identifier.
resource string, always key Resource type specifier.
organisation organisation ID The organisation this key belongs to.
type string One of: standard, trial.
storage_config optional, storage config ID The storage config used by the key.
webhook_config optional, webhook config ID The webhook config used by the key.
token string The auth material for this key. Is used to populate the AUTHORIZATION HTTP header in requests against the API.
state string One of: active, deactivated, blocked, expired.
date_created datetime When the resource was created.
date_expires optional, datetime When the key will expire. Mainly applies to trial type keys.

Types

standard
the key type. Every organisation has at least one of these.
trial
a key generated by an API administrator to give the organisation trial access to additional permissions. These will typically have the date_expires field set.

Storage and webhook configs

A key resource can override the organisation default values for storage and webhook config. This can be helpful to split results and event notification between environments like dev and production.

Token

The value of a key's token attribute can be used to authenticate against the API on behalf of the owning organisation.

These values should be stored securely and never exposed publicly.

State

active
the key's standard state.
deactivated
the owning organisation has disabled the key.
blocked
the key has been disabled by an API admin.
expired
the key is disabled as the trial period has passed.

Create POST /keys

Parameters

name type description
storage_config storage config ID Override the organisation's default storage config on this key.
webhook_config webhook config ID Override the organisation's default webhook config on this key.

Using cURL

curl 'https://ricloud-api.reincubate.com/keys' \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "storage_config": 2,
}'

Using ricloud-py

import ricloud

key = ricloud.Key.create(storage_config=2)

# OR

storage_config = ricloud.StorageConfig.retrieve(2)

key = ricloud.Key.create(storage_config=storage_config)

Retrieve GET /keys/{key ID}

Using cURL

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

Using ricloud-py

import ricloud

key = ricloud.Key.retrieve(<key ID>)

List GET /keys

Parameters

name type description
type string Filter keys by their type.
state string Filter keys by their state.

Using cURL

curl 'https://ricloud-api.reincubate.com/keys?limit=2' \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

keys = ricloud.Key.list(limit=2)

Update POST /keys/{key ID}

Parameters

name type description
storage_config storage config ID Update the storage config used by the key. If null will fall back to organisation default.
webhook_config webhook config ID Update the webhook config used by the key. If null will fall back to organisation default.

Using cURL

curl 'https://ricloud-api.reincubate.com/keys/<key ID>' \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "webhook_config": 2
}'

Using ricloud-py

import ricloud

key = ricloud.Key.update_with_id(<key ID>, webhook_config=2)

# OR

key = ricloud.Key.retrieve(<key ID>)

key.update(webhook_config=2)

Rotate POST /keys/{key ID}/rotate

Rotate the value of a key's token. Although not required, it is recommended to do this on a fairly regular basis or immediately if it is suspected the key's token has been compromised.

Parameters

name type description
force bool, default: False If the current token value should be deauthorized immediately. If not, the current rotation period is 6 hours after the call is made.

Using cURL

curl 'https://ricloud-api.reincubate.com/keys/<key ID>/rotate' \
  -X POST \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

key = ricloud.Key.rotate_with_id(<key ID>)

# OR

key = ricloud.Key.retrieve(<key ID>)

key.rotate()

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:52 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

© 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.