API Access

An API Key instance sub resource represents an api key entity. API keys allows external or internal entities to interact with the Connio platform securely. Every transaction of API keys are recorded to be used for audit and billing purposes.

Note that API keys do not exist by their own; instead they are always created automatically under a parent entity such as user, device or apiclient. We call these keys User Key, Device Key, and Client Key respectively.

Resource Attributes

AttributeDescription
ContextIt consists of type and ids fields. type can be one of the following account, app, and device. The ids field contains a set of entity ids matching the given context type.
ScopeScopes let you specify exactly what type of access you need. Scopes limit access for api keys. See the scope table below for more information.
RateLimitAs its name suggests, it limits the transaction rate of this api key. Default value for this attribute is defined by the account type, and cannot be changed by the user. Can be unlimited (-1) or x number of calls per minute.
{
  "id": "_key_924201752433266229",
  "secret": "85f0b8497fab4244b63439b23fe148d0",
  "ownerId": "_usr_924201603387295292",
  "accountId": "_acc_923380065327020781",
  "context": {
    "type": "account",
    "ids": [
        "_acc_923380065327020781"
    ]
  },
  "scope": [
    "app:read-data",
    "device:read-data",
    "deviceprofile:read",
    "device:read",
    "device:modify",
    "device:write-data",
    "subaccount:read",
    "appprofile:modify",
    "deviceprofile:modify",
    "app:modify",
    "account:read",
    "app:read",
    "appprofile:read",
    "apiclient:read"
  ],
  "rateLimit": 60,
  "dateCreated": "2017-06-29T03:43:54.309Z",
  "dateModified": "2017-06-29T03:43:54.309Z"
}

Context

Context defines the context that this api key will be applicable. For example if the context is set to app with ids field ['_app_156238482748283274'], and the scope attribute is set to app:read, external system using this key can read the metadata of the app with the given id.

In some scenarios, devices do not get connected to the Connio platform directly. Instead, an external backend system exchange data with the Connio platform on behalf of these devices. In such cases, it is useful to provide a single api key to the external backend system instead of multiple keys. Below we show an example api client's key meeting the requirements of this scenario:

{
  "id": "_key_465924116351130803",
  "secret": "66b61659cd7a4885bec0756d9ef97ea4",
  "accountId": "_acc_466239243174908338",
  "context": { 
    "type": "device", 
    "ids": ['_dev_467084708689467300', '_dev_467084708689467301', '_dev_467084708689467302'] 
  },
  "scope": ['device:read', 'device:read-data', 'device:write-data', 'device:execute-method', 'device:modify'],
  "rateLimit": 120
}

Acceptable context types are:

TypeDescription
accountGives access to specific accounts for management. The owner account id or a set of sub accounts can be provided as id list. All user api keys runs in account context.
deviceGives access to specific devices. This key can be used to read/write data from/to the specified devices. Each device gets an api key automatically when created, device being its context type containing all device related scopes.
appGives access to specific apps. With proper scope, this key can be used to manage (i.e. add, remove properties etc.), and/or to read/write data from/to the specified apps.

๐Ÿšง

Rule

Only devices generated from Gateway device profile can carry multiple device ids in their api keys. Other devices can have only single device id in their api key.

๐Ÿ“˜

Tip

Api Client is generic entity that might represent any kind of external or internal agent that interacts with the Connio platform. It is the only entity that might have all three context types in it api keys (not at the same time off course). Like devices, each api client gets an api key automatically when created.

Scope

Scope defines the privileges given to a api key. Each context works with different sets of scopes. Valid scopes are:

ScopeDescriptionContext
(no scope)Grants read-only access to public information.all
subaccount:createAllows sub account creation.account
subaccount:readGrants read-only access to all sub account data.account
subaccount:modifyAllows sub account data modification.account
subaccount:deleteAllows sub account deletion.account
user:createAllows user creation.account
user:readGrants read-only access to all user data.account
user:modifyAllows user data modification.account
user:deleteAllows user deletion.account
apiclient:createAllows api client creation.account
apiclient:readGrants read-only access to all api client data.account
apiclient:modifyAllows api client data modification.account
apiclient:deleteAllows api client deletion.account
deviceprofile:createAllows device profile creation.account
deviceprofile:readGrants read-only access to all device profile data.account
deviceprofile:modifyAllows device profile data modification.account
deviceprofile:deleteAllows device profile deletion.account
device:createAllows device creation.account
device:readGrants read-only access to all device data.account, device, app
device:read-data*Allows reading device captured data from the time-series database and device state.account, device, app
device:write-data*Allows writing data to the platform on behalf of a device.device, app
device:executeAllows public method execution on the device.account, device, app
device:modifyAllows device data modification.account, device
device:deleteAllows device deletion.account
appprofile:createAllows app template creation.account
appprofile:readGrants read-only access to all app template data.account
appprofile:modifyAllows app profile data modification.account
appprofile:deleteAllows app profile deletion.account
app:createAllows app creation.account
app:readGrants read-only access to all app data.account, app
app:read-dataAllows reading app captured data from the time-series database and app state.account, app
app:write-dataAllows writing data into app properties.app
app:executeAllows public methods execution on the app.account, app
app:modifyAllows app data modification.account, app
app:deleteAllows app deletion.account

(*) If the key's is a API Client or User key, it can access only to public properties of the device for reading and writing. If the key's owner entity is a device, it can access to all its properties including private and public ones.

Device, and User keys

API Keys that are automatically generated for device, and user entities are called Device Keys, and User Keys respectively.

Device Key allows any physical device or data source to:

  • Read device state including the most recent property values
  • Read device metadata and historical data
  • Write device data to the platform
  • Execute device methods
  • Connect to the platform through one of the supported connection methods such as MQTT or WebSocket (read & write)

User Key allows account users to:

  • Managed the given account entities including sub accounts, apps, devices, device profiles, etc..

A fully privileged Api Client with App context allows any app client to:

  • Read app state including the most recent property values
  • Read app metadata and historical data
  • Execute app methods
  • Write app data to the platform
  • Connect to device mirrors
  • Read device state including the most recent property values
  • Read device historical data
  • Execute device methods

User roles

For convenience, when creating new users, roles can be specified. Connio API supports 3 predefined roles as such:

RoleDescriptionScopes
adminFull system administration privileges-
powerPower user. Full system administration privileges minus account closing, user creation, modification , deletion and api key regeneration-
userRegular user. Mostly read-only access to account entities-
guestVery limited access-

Api Key Usage

The following Data Services endpoints can be used with the following api keys.

Device Key

OperationHTTP VerbEndpointShortcut
WritePOSTdata/devices/_this_/properties/data/properties
WritePOSTdata/devices/_this_/properties/{ref}/data/properties/{ref}
ReadGETdata/devices/_this_/data
ReadGETdata/devices/_this_/properties/{ref}/data/properties/{ref}
ExecPUTdata/devices/_this_/methods/{ref}/data/methods/{ref}

ref can be id or name

_this_ is a special keyword to refer to the device associated with the given device key, without using device id or name.

API Client Key (Generic Key) with App context and full app access privilege

OperationHTTP VerbEndpointShortcut/Notes
WritePOSTdata/apps/{ref}/propertiesNone
WritePOSTdata/apps/{ref}/properties/{ref}None
ReadGETdata/apps/{ref}None
ExecPUTdata/apps/{ref}/methods/{ref}None
WritePOSTdata/devices/{ref}/propertiesSend command to a plugged device
WritePOSTdata/devices/{ref}/properties/{ref}None
ReadGETdata/devices/{ref}Read plugged device state
ReadGETdata/devices/{ref}/properties/{ref}Read plugged device property
ExecPUTdata/devices/{ref}/methods/{ref}Execute plugged device method

App keys can only access to the devices plugged into this app. ref can be id or name

API Client Key (Generic Key) with Device context and full device access priviledge

OperationHTTP VerbEndpointShortcut/Notes
WritePOSTdata/devices/{ref}/propertiesSend command to a plugged device
WritePOSTdata/devices/{ref}/properties/{ref}None
ReadGETdata/devices/{ref}Read plugged device state
ReadGETdata/devices/{ref}/properties/{ref}Read plugged device property
ExecPUTdata/devices/{ref}/methods/{ref}Execute plugged device method

๐Ÿ“˜

Tip

Generic api keys created with Device context can act on behalf on the devices listed in the ids array.