The best security features are those that allow you to better implement battle-tested fundamental security best practices. We’re confident that our latest feature, launching today, fits this description perfectly.
API users are a special kind of user account you can add to your Particle product or organization. Unlike regular Particle user accounts, which are designed primarily for ‘human’ users, an API User is perfect for a machine-to-machine interaction with the Particle Device Cloud, such as in a script, or your server-side code.
API users are given granular access to Particle API. By assigning them specific API scopes, you’re ensuring they only have the ability to perform the functions they need to, and nothing more. This is somewhat different from regular user accounts, which inherit scopes based on their account role.
Here is what you need to know about an API user:
An API user can be scoped to an organization or a product.
An API user can only have one valid access token associated with it at any one time.
If an API user’s privileges change – the associated access token will change as well, to prevent ‘scope creep.’
Currently, API users are created, updated and deleted via the REST API, and are visible in the console in either the product team or organization team view.
API users cannot log into the console, administer users, receive emails, or generally do other things that are reserved for humans.
API response after creating an API user
An API user as viewed in the Particle Device Cloud Console
Further reading:
The Particle Device Cloud API documentation has been updated with full details of how to create, update and delete an API user.
This is a very big step forward for API management. I have just started to dive in here so I hope I can ask some questions that may be common:
I have created an API User for my organization and scoped its permissions. What about expiration of the token? Do these tokens expire? Can set a policy for this?
I love the you have created an API tutorial to make it easier to use the API. There is an issue with using this (in Chrome and Safari at least) if you are a member of more than one organization, the products for your “second” organization do not get populated.
Is there any chance that this App Note could be updated with this new capability. It seems to me that API Users is the perfect way to mitigate the risk called out in this app note - “The downside to this is that you must include a Particle account access token in your script. This token grants full access to your account, so beware!” With API users it seems you could use a token that can only do this look up.
That said, given how granular the controls are with API Users, any chance you might point me to the one that would be needed for this function? I assume it is either device.get or device.list.
Thanks for reaching out, answers to questions below:
Currently, API users don’t support pre-defined expiration times when they are created, this is just to avoid disrupting any automated processes that rely on them. They can however be ‘expired’ by deleting and recreating the user (which itself could be done programmatically if desired), or if you update the scopes associated with them. Happy to take setting expiration times as a feature request, however. Personally, I’m a fan of supporting both set expiration times, and also expiration on a rolling basis (e.g. expire if token not used for x days).
Will pass that feedback on to the correct person over here to take a look at supporting multiple orgs in tutorials.
Postman collection was updated last week to include the API Users endpoints, make sure you have the latest version from this link and you should be good to go.
Yes, this needs updating now (will get that taken care of) and this is exactly what API users were designed to address. In this example, the scope the API user would need is devices:list. Remember however that the API user is scoped to a product or org, so the API URL called would have to be modified to include the product ID or slug, or org ID or slug, i.e. GET https://api.particle.io/v1/products/:productIdOrSlug/devices, instead of GET https://api.particle.io/v1/devices.
Hello Mike,
If we have an organizational API token, how do I use it to get the properties of a device. Is it some thing like https://api.particle.io/v1/:Organizaion/devices/:deviceId.
I tried several similar combinations but none worked. Can you please provide some help.
The idea is that the organization is a collection of products and users in that organization, however the devices are still either associated with a product or user, so the product or user APIs are used. The organization APIs are only for managing the collection of products, users, and authentication tokens.
This also makes it much easier to migrate from a product (even in the free tier) all the way up to an enterprise organization without any of the API endpoints changing.
@mike.sheward Taking this step further, is there a way to limit an API user to only specific devices under a product and also allow that users to run the device functions?