For most of the calls to AllThingsTalk API, your client must obtain a valid access token. Access tokens are opaque strings that identify clients (devices, users or apps) and are used by AllThingsTalk to authenticate and authorize client’s API calls. A token includes information about when it will expire (if ever) and which authority has issued the token.
A Device Token is an access token that you can embed into native device binary or sketch to identify your device client application. The token is usually embedded in the application configuration, and the only way to change it is to manually rewrite the token and reboot the app.
A client that presents a valid Device Token has device-level access:
Device Token doesn’t allow client to access system- or user-level resources such as Grounds or Rules.
To get a Device Token for a device on the Cloud:
GENERATE NEW TOKEN
, and also delete any of themIf you wish to authenticate a client application to access multiple devices within a ground, you can use Ground Tokens.
Example:
Say you are monitoring the temperature readings on different locations with IoT devices. You have rolled-out the devices in a ground, called ‘Temp-a-ground’.
Using a single Ground Token, you can configure a client application to subscribe to temperature asset state of all devices within the ‘Temp-a-ground’.
This allows you to easy aggregate and manage all necessary IoT sensor data which serves your application. Customers with access to your application do not need to have access rights to the IoT devices and asset data which improves the security model of your IoT solution.
A client that presents a valid Ground Token has device-level access for each device in the ground:
Ground Token doesn’t allow client to access system- or user-level resources such as Rules.
To get a Ground Token for a ground:
GENERATE NEW TOKEN
, and also delete any of themAt this stage, OAuth2 is not entirely supported - you cannot create your own application and grant access. Consider using Device Tokens for authorizing simple applications.
User clients (usually browser and mobile apps) are authenticated using the OAuth2 authorization protocol.
Currently the following types are supported as APPLICATION_ID
for the client_id
parameter (see below)
To get a new access token for username and password, your client must send the following parameters:
HTTP request headers
Content-Type: application/x-www-form-urlencoded
HTTP body parameters
grant_type=password
username
password
client_id
grant_type=password&username=someusername&password=somepassword&client_id=APPLICATION_ID
Example:
Send 'POST' request to URL: https://api.allthingstalk.io/login
Post parameters : grant_type=password&username=batman&password=iambatman&client_id=maker
Response Code : 200
{
"access_token": "some_encrypted_token_value",
"token_type": "bearer",
"expires_in": 3599,
"refresh_token": "some_refresh_token",
"as:client_id": "maker",
"userName": "someusername",
".issued": "Wed, 20 Aug 2014 14:55:38 GMT",
".expires": "Thu, 21 Aug 2014 14:55:38 GMT"
}
After initial access token expires, your client must refresh it. This is done by providing the refresh_token
received in the login response. To exchange a refresh_token
for a new access_token
, a POST
request needs to be sent to https://api.allthingstalk.io/login
as follows:
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID
Refresh tokens can expire too, but their expiry time is much longer, set to 60 days.
{
"access_token": "some_new_encrypted_token_value",
"token_type": "bearer",
"expires_in": 3599,
"refresh_token": "some_new_refresh_token",
"as:client_id": "maker",
"userName": "someusername",
".issued": "Fri, 22 Aug 2014 12:52:22 GMT",
".expires": "Fri, 22 Aug 2014 13:52:22 GMT"
}
Now that you’ve learned how to authenticate your client, go on and learn how to Implement your first IoT device.