API Endpoints

The following functions are being exposed via the RESTful API:

Before you begin using the API below, be sure you have read the information in Afero Cloud API.


OAuth Authentication

The OAuth Authentication endpoint is used to authenticate end-users and generate an access key, which will be used to authenticate requests on behalf of the end-user. For this endpoint, you will need your OAuth Client ID and OAuth Client Secret, which you can view by signing in to the Afero Profile Editor, then opening the Settings > My Account screen.

Request

Resource
URL
HTTP
Method
Request Headers Request Payload
oauth/token POST
{
	"Content-Type": "application/x-www-form-urlencoded",
	"Accept": "application/json",
	"Authorization": "Basic ABC9g1Zso4P6wKLebTFcNb=="
}
{
   "username": "username@afero.io",
   "password": "user_password",
   "grant_type": "password"
}

Example Response

{
	"access_token": "12345678-90AB-CDEF-0123-FED789CBA432",
	"token_type": "bearer",
	"expires_in": 16086,
	"scope": "partner account"
}

Notes

  • The Authorization header value should be the string Basic, followed by a space, followed by a token string. That token is a Base64 encoded representation of your OAuth Client ID, a colon, and then your OAuth Client Secret.

    For example, if your ClientID was “Mork” and your Client Secret was “Mindy”, you would perform a Base64-encoding of Mork:Mindy to create the token TW9yazpNaW5keQ==

    The entire Authorization header value would be Basic TW9yazpNaW5keQ==.

  • In the Request Payload, the username and password are the username and password you chose when you activated your Afero account.
  • The access token returned in the response must be provided in subsequent API requests (see below), and this value expires.
  • The expiration parameter in the response, expires_in, is measured in seconds.

Get Information About a User

The users/me endpoint provides a variety of user-specific information useful for personalization and other tasks.

Request

Resource URL HTTP Method Request Headers Request Payload
v1/users/me GET
{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "Authorization": "Bearer <oauth access_token>"
}
Not applicable.

Example Response

{
	"accountAccess": [
	{
	   "account": {
		  "accountId": "acdf8add-h15f-495e-8156-b4cfad3fd402",
		  "createdTimestamp": 1449162900727,
		  "description": "Primary Account",
		  "type": "CUSTOMER"
	   },
	   "privileges": {
		  "canWrite": true,
		  "owner": true
		  }
	   }
	],
	"credential": {
	   "credentialId": "mike@sample.com",
	   "failedAttempts": 0,
	   "lastUsedTimestamp": 1449166732313,
	   "type": "EMAIL",
	   "verified": true
	   },
	   "firstName": "Mike",
	   "lastName": "Smith",
	   "partnerAccess": [
		  {
			 "partner": {
				"clientId": "asdf13228-234e-427d-add6-5asdf2jfacdf72",
				"clientSecret": "asdf23ewf14wf34rgdcdf34ewdage",
				"createdTimestamp": 1443458477948,
				"name": "Mike's Devices",
				"partnerId": "acdf13228-234e-427d-add6-5abdf2jfacdf72"
			 },
			 "privileges": {
				"inviteUsers": true,
				"manageDeviceProfiles": true,
				"owner": true,
				"viewDeviceInfo": true
			 }
		  }
	   ],
	   "tos": [
		  {
		  "currentVersion": 1,
		  "needsAcceptance": false,
		  "tosType": "user",
		  "url": "https://cdn.afero.io/tos/user/v1/user.html",
		  "userVersion": 1
	   },
	   {
		  "currentVersion": 1,
		  "needsAcceptance": true,
		  "tosType": "developer",
		  "url": "https://cdn.afero.io/tos/developer/v1/developer.html",
		  "userVersion": 1
	   },
	   {
		  "currentVersion": 1,
		  "needsAcceptance": true,
		  "tosType": "general",
		  "url": "https://cdn.afero.io/tos/general/v1/general.html",
		  "userVersion": 1
	   }
	],
	"userId": "123acdfa-asd2-4b26-2cd2-68cfe2acdd8b8"
}

List Current Devices and State Information

List devices associated with the specified account.

Request

Resource URL HTTP Method Request Headers Request Payload
v1/accounts/{accountId}/devices GET
{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "Authorization": "Bearer <oauth access_token>"
}
Not applicable.

Example Response, with State Expansion

http://api.afero.io/v1/accounts/acdf8add-915f-495e-8156-b4cfad3fd402/devices?expansions=state

The response below includes details for two devices. Note that this view includes the deviceState key and associated data.

[
  {
	 "deviceId": "f381c366-e102-4d01-b64e-1708ebbd1a7c",
	 "profileId": "51415861-0d19-4c54-9c44-42f799fa96a2",
	 "updating": false,
	 "createdTimestamp": 1448315207125,
	 "deviceState": {
	   "available": false,
	   "visible": false,
	   "dirty": false,
	   "rebooted": false,
	   "connectable": false,
	   "connected": false,
	   "rssi": 0,
	   "linked": false,
	   "updatedTimestamp": 1448993366236
   },
   "virtual": false,
   "disconnectNotificationLevel": "LOW",
   "friendlyName": "prototype_1",
   "developerDevice": false,
   "partnerId": "acdf13228-234e-427d-add6-5abdf2jfacdf72",
   "deviceTypeId": "50895f74-5b6f-48a3-9b97-0d26909e0a59"
 },
 {
   "deviceId": "01234462d72ca571",
   "profileId": "855710b5-421c-498c-83e1-1c20a8f25568",
   "updating": false,
   "createdTimestamp": 1447801902003,
   "deviceState": {
	 "available": false,
	 "visible": false,
	 "dirty": false,
	 "rebooted": false,
	 "connectable": false,
	 "connected": false,
	 "rssi": 0,
	 "location": {
	   "latitude": "37.39750353571521",
	   "longitude": "-122.1063402868886",
	   "lastUpdatedTimestamp": 1448490948016
	 },
	 "linked": true,
	 "updatedTimestamp": 1448650832509
   },
   "virtual": false,
   "disconnectNotificationLevel": "MEDIUM",
   "friendlyName": "autoMate",
   "developerDevice": true,
   "partnerId": "acdf13228-234e-427d-add6-5abdf2jfacdf72",
   "deviceTypeId": "a9fccc1d-b2e1-4822-b4e2-d301b762bd75"
 }
]

Example Response, with Tags Expansion

http://api.afero.io/v1/accounts/acdf8add-915f-495e-8156-b4cfad3fd402/devices?expansions=tags

This is a partial response, showing data for just one device to illustrate the data displayed when the tags expansion is applied. In this case, we see the deviceTags key and associated data.

...
  {
	"disconnectNotificationLevel": "LOW",
	"deviceTags": [
	  {
		"deviceTagType": "SYSTEM",
		"deviceTagId": "45f447db-c312-41a4-9a5c-ab81609cf22a",
		"value": "Entertainment",
		"localizationKey": "entertainment"
	  }
	],
	"virtual": False,
	"createdTimestamp": 1449262135070,
	"deviceTypeId": "a9fccc1d-b2e1-4822-b4e2-d301b762bd75",
	"developerDevice": False,
	"partnerId": "acdf13228-234e-427d-add6-5abdf2jfacdf72",
	"deviceId": "d702ec02-29f4-4aa6-ae0a-30d13616f19c",
	"friendlyName": "",
	"profileId": "855710b5-421c-498c-83e1-1c20a8f25568",
	"updating": False}
...

Example Response, with Attributes Expansion

http://api.afero.io/v1/accounts/acdf8add-915f-495e-8156-b4cfad3fd402/devices?expansions=attributes

This is a partial response, showing data for just one device to illustrate the data displayed when the attributes expansion is applied. In this case, we see the attributes key and associated data.

...

{
   "deviceId": "f381c366-e102-4d01-b64e-1708ebbd1a7c",
   "profileId": "50895f74-0819-4744-9a44-42f798ed96a2",
   "updating": false,
   "createdTimestamp": 1448315207125,
   "virtual": false,
   "disconnectNotificationLevel": "LOW",
   "friendlyName": "prototype_1",
   "attributes": [
	 {
	   "id": 1024,
	   "data": "0000",
	   "updatedTimestamp": 1448650643768
	 },
	 {
	   "id": 1025,
	   "data": "0100000000000000",
	   "updatedTimestamp": 1448650643908
	 },
   ],
   "developerDevice": false,
   "partnerId": "acdf13228-234e-427d-add6-5abdf2jfacdf72",
   "deviceTypeId": "50895f74-5b6f-48a3-9b97-0d26909e0a59"
 }
...

Notes

  • This request can be modified with ‘expansions’ to select the type of information that will be returned. Three expansions are available: state, tags, and attributes. They are used by adding them as parameters to the request URL, as shown below.

Execute an Action on a Device

To execute an action on a given device, submit a request that defines an attribute ID to set, and the value to set it to. In the example below, we are setting attribute ID 1 to value 1 (perhaps to turn on a fan).

Request

Resource URL HTTP Method Request Headers Request Payload
v1/accounts/{accountId}/devices/{deviceId}/actions POST
{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "Authorization": "Bearer <oauth access_token>"
}
{
 "type": "attribute_write",
 "attrId": 1,
 "data": "01"
}

Example Response

{
	"type": "attribute_write",
	"requestId": 14,
	"timestampMs": 1449267297894,
	"sender": "ClientApi",
	"source": {
	"type": "user",
	"userId": "123acdfa-asd2-4b26-2cd2-68cfe2acdd8b8",
	"firstName": "Mike",
	"lastName": "Smith"
	},
	"attrId": 1024,
	"data": "0000"
}

Notes

In the Request Payload:

  • The value for type can be either attribute_read or attribute_write. Of course, the specified attribute must support the corresponding operation.
  • The value for data must be hexadecimal encoded (little endian).

Update the Friendly Name of a Device

Change the friendly name of the specified device. This name is visible in the Afero Profile Editor.

Request

Resource URL HTTP Method Request Headers Request Payload
v1/accounts/{accountId}/devices/{deviceId}/friendlyName PUT
{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "Authorization": "Bearer <oauth access_token>"
}
{
 "friendlyName": "cool_new_name"
}

Example Response

{
 "friendlyName": "cool_new_name"
}