Choose an access token type
Every ARTIK cloud services API call requires an access token. There are three token types, and it's important to understand when to use each.
Get to know the basics of user tokens, application tokens, and device tokens.
We use the below example system in this guide.
This is a typical system developed with ARTIK cloud services. Your use case may differ (e.g. no backend server for acessing user data), but these best practices apply to all systems.
Our example system contains three components:
- Devices send/receive messages/Actions to/from ARTIK cloud services.
- A device owner logs into ARTIK cloud services with a user app (mobile, desktop, or web). The end user can then view and control his/her devices via ARTIK cloud services.
- A backend server app manages/controls the devices owned by all end users. For example, the server app performs data analysis on the device data from the user base.
The user app and server app are companion apps developed by the same company. They must share a client ID (aka application ID) in ARTIK cloud services.
Devices and applications from different companies are interoperable on ARTIK cloud services.
Note the token types indicated for the three components:
- Devices use device tokens.
- A user app uses a user token.
- A backend server app uses an application token.
A physical device should use a device token when making API calls to exchange data with ARTIK cloud services. This is because:
- The device token accesses information pertaining only to this device (not to other devices or users).
- The device token has no expiration time and does not need to be refreshed. It expires only if the token is proactively revoked via API call or My ARTIK Cloud.
This article describes use cases of onboarding physical devices in which the device token is preferred (e.g. device with user login capability, device with a proxy app). The device token is created during onboarding.
We refer here to devices that communicate directly with ARTIK cloud services via API calls. Cloud Connector devices are not relevant because they communicate with external clouds using third-party APIs.
A user app must obtain and use a user token because:
- This is the only way a user can grant the permissions requested by the application when it is created in the Developer Dashboard. Permissions must be granted before the app can access a user's data.
- The user token accesses information pertaining only to the devices of the logged-in user (not to other users' devices).
There are multiple OAuth methods for obtaining a user token. Each is suited to a different scenario:
- If the user app is a web application, use Authorization Code.
- If the user app is an installed app (desktop or mobile app), use Authorization Code with PKCE.
- If the user app is a client app running only in a web browser, use Implicit. This method is less secure than the others and should only be used for this case.
For more information, see the companion article on choosing an OAuth2 method.
User tokens have a limited lifetime. A user app should implement token refresh functionality.
Backend server application
A backend server app should use an application token because:
- This is the only token type that can access data across devices and users.
- Obtaining an application token does not require user interaction (in contrast to obtaining a user token). Prompting a user to login is not feasible for a backend server app.
Use the Client Credentials method to easily obtain an application token. The token is short-lived. Since there is no login UI involved, it is convenient to obtain an application token whenever one is needed.
A backend server app must have a companion user app. Before the server app can access a user's data with an application token, the end user must have granted it permissions on his/her data with the user app. This is possible because the user app and server app have the same application ID on ARTIK cloud services.