Authentication

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.

Device Tokens

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.

Device Token access level

A client that presents a valid Device Token has device-level access:

• Add and configure assets
• Publish asset state
• Read asset feed
• Receive asset commands

Device Token doesn’t allow client to access system- or user-level resources such as Grounds or Rules.

Get a Device Token

To get a Device Token for a device on the Cloud:

• Select a device for which you need a token
• In the upper right corner choose DEVICE SETTINGS > Authentication
• Device Token is created on device creation; copy it and use it in your device client application
• You can generate multiple tokens by clicking GENERATE NEW TOKEN, and also delete any of them

Ground Tokens

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

Ground Token access level

A client that presents a valid Ground Token has device-level access for each device in the ground:

• Add and configure assets
• Publish asset state
• Read asset feed
• Publish asset commands
• Receive asset commands

Ground Token doesn’t allow client to access system- or user-level resources such as Rules.

Get a Ground Token

To get a Ground Token for a ground:

• Select a ground for which you need a token
• From the ground menu select Settings
• Ground Token is created on device creation; copy it and use it in you client application
• You can generate multiple tokens by clicking GENERATE NEW TOKEN, and also delete any of them

OAuth2

At this stage, OAuth2 is not entirely supported - you cannot create your own application and grant access. Consider using Ground 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 client_id parameter (see below)

• web - Used by our web app
• mobile - Used by our mobile apps
• postman - A generic Client ID being used by your Postman client

Get OAuth2 Token

To get a new access token your client needs to pass the MFA flow, meaning that it has to authenticate with username and password, and then to provide a valid verification code from the authenticator app running on your phone.

Authenticate:

1
2
3
4
5
6

curl --location --request POST 'https://api.allthingstalk.io/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<YourUsername>' \
--data-urlencode 'password=<YourPassword>' \
--data-urlencode 'client_id=web'

This will return something like:

1
2
3
4
5

{
    "QrCodeURL": null,
    "MfaUid": "1772f59085744675ab62c69137f9d056",
    "UserId": "5e41321da9d69f0001c0e0b5"
}

You will need to grab MfaUid and UserId and provide them in the next request.

Verification code:

1
2
3
4
5
6
7

curl --location --request POST 'https://api.allthingstalk.io/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=mfa' \
--data-urlencode 'userid=<UserId>' \
--data-urlencode 'mfauid=<MfaUid>' \
--data-urlencode 'client_id=web' \
--data-urlencode 'code=<VerificationCodeFromAuthenticatorApp'

This will return the object holding the User token as access_token:

{
  "access_token": "encrypted_token_value",
  "token_type": "bearer",
  "expires_in": 3599,
  "refresh_token": "refresh_token",
  "as:client_id": "web",
  "userName": "username",
  ".issued": "Wed, 20 Aug 2014 14:55:38 GMT",
  ".expires": "Thu, 21 Aug 2014 14:55:38 GMT"
}

Refresh token

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, do this:

1
2
3
4
5

curl --location --request POST 'https://api.allthingstalk.io/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=<refresh_token>' \
--data-urlencode 'client_id=web'

Refresh tokens can expire too, but their expiry time is much longer, set to 60 days.

Where to go next?

Now that you’ve learned how to authenticate your client, go on and learn how to Implement your first IoT device.