Access tokens

Access tokens control access to the Particle Cloud API. While you can use a username and password, and optionally a multi-factor authentication (MFA) code to log into things like the console, behind the scenes this creates an access token that is used to access the cloud API on your behalf.

Devices don't use access tokens; they use a different technique (RSA public-private key pairs) to securely access the cloud. This makes it difficult to spoof or impersonate a device, and also assures that even if you have physical access to a device you can't extract anything that would be able to access the owner's account information.

There are many different types of access tokens and ways of handling them. This document details access the cloud by a developer, product owner, or server. There is also a separate document on oAuth authorization that describes less-common scenarios for interacting with customer devices from a mobile app or server, sometimes used with Wi-Fi devices.

In order to use the interactive features of this page we recommend logging into your account if you have not already done so.

Getting a user access token

CLI particle token create

The most common create a user access token is to use the Particle CLI particle token create command.

Be sure to keep this token secure, because it allows access to your account and all of your devices. By default, the token will expire in 90 days and will need to be issued again. You can make a non-expiring token by using:

Create a token (browser-based)

You can also create a token using this web-browser control. This creates a token for your account, which can access all devices in your sandbox as well as products and organizations you have access to. Be careful with this token! The username, password, and MFA OTP token (if required) are necessary to create a new token.

Copy and paste the token out of the Access Token field to use in locations where you need an access token. (The password is sent using a Particle Cloud API call using Javascript and TLS/SSL encryption.)

API rate limits

You should not create a new access token for each API operation! You should instead create one at most for each session, and save the token and reuse it where it's safe to do so. The limits for access token and general API calls are:

Create an access token - API rate limits

All API functions - API rate limits

Getting an API user token

Both of the techniques above create a user-based access token, which is appropriate for experimenting and some other use cases.

The API user feature makes it possible to create a non-expiring access token that only allows access to certain Particle cloud APIs. If you have a back-end that only uses a small number of APIs, using an API user can be more secure than using a user token.

Create API user

	Product Organization
	Sandbox Product Organization Product
Organization
Product
Friendly Name
Scopes

Request:

Response:

List or delete API users

	Product Organization
	Sandbox Product Organization Product
Organization
Product

Request:

Response:

To delete an API user, list the users in the product or organization. If there are API users defined, a user selector and a Delete User button will appear.

Creating a customer token (oAuth)

Customer claiming and customer tokens are typically only used for Wi-Fi device with an associated mobile app, and are not required, even in that scenario.

Creating a product bearer token (oAuth)

Before the API User feature (above), the only way to access all devices in a product is with a product bearer token. It's generally better to use the API user feature now, because it allows the token to be restricted to only the operations it needs to be able to perform.

Using with servers

When you implementing a server, you may not want to use interactive login. You should instead have a pre-generated login token and store that in a secure location. This is typically:

Most cloud-services should include the access token in an environment variable. They generally provide a secure way to store and pass these variables to your cloud server or cloud function.

In some cases, it may be appropriate to store the access token in a configuration file, but make sure you never commit that file to a public source code repository!

Using an environment variable

The Try It button opened a new web browser which allows you to test the node.js application with no software install required on Windows, Mac, Linux, or Chromebook. The node.js Try It feature only works on Chrome browsers.

To call the script, you just get an access token (above), and set the environment variable first.

For the Try It web-based example, enter the command in a single line in the terminal box at the bottom of the window.

Of course replace 27fdffffffffffffffffffffffffffffffff4259 with your access token. This must be a user access token, not an API user token.

Prompting for login

There are a number of reasons you would want to prompt for login instead of requiring a token:

Logging in this way requires a username, password, and, if enabled in the account, a MFA (multi-factor authentication) security code. Once you obtain an access token for the user, that token will have access to the developer sandbox, products, and organizations that the user has access to.

From a web page

This is a simple example project for prompting for Particle authentication from a web page. Once logged in it creates a popup menu with a list of devices just an an example.

The Try It button will open up a separate web browser window where you can try the web page, as well as edit the code. This example, which only uses HTML and Javascript, should work with all major web browsers.

From a node.js command line tool

Log in using:	Username and Password Access token
Username (Email):
Password:
Maximum time to stay logged in:
Access token:

User Email
Password
Expires In
MFA OTP Token		(6 digits)

Access Token

Log in