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

{
  "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:

🚧

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:

(*) 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:

Api Key Usage

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

Device Key

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

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

📘

Tip

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