Introducing API Users

Originally published at: Introducing API Users – Particle Blog

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.
A view of API users in ParticleAPI response after creating an API user A view of API user in the Particle Device Cloud ConsoleAn 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.

See: https://docs.particle.io/reference/device-cloud/api/#api-users for more information.

6 Likes

@mike.sheward

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:

  1. 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?

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

https://docs.particle.io/tutorials/device-cloud/cloud-api/#api-users

  1. I love the tutorial and the curl commands in the reference docs. Any chance Particle might publish a collection for these API calls in Postman?

  2. I am using a webhook to send data to GoogleSheets as published in AN011:

https://docs.particle.io/datasheets/app-notes/an011-publish-to-google-sheets/

There is a section where you use the Particle API to get the device name that corresponds to the device ID.
https://docs.particle.io/datasheets/app-notes/an011-publish-to-google-sheets/#mapping-device-ids-to-names-using-particle-cloud-api-

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 again for this great work.

Chip

Hi Chip,

Thanks for reaching out, answers to questions below:

  1. 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).

  2. Will pass that feedback on to the correct person over here to take a look at supporting multiple orgs in tutorials.

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

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

Cheers,

Mike

1 Like

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.

Thanks,

Arvind

You use product routes for organization products:

GET /v1/products/:productId/devices/:deviceId

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.

Thanks Rick for the clarification. I will give that a try.

The API User Tutorial is INVALUABLE!!!
I mean, creating and sending the right requests from the browser. Just Wow.
Thank you.

1 Like

@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?

Taking this step further, is there a way to limit an API user to only specific devices

No, that's not a a feature of API users. That's often what customers are used for, however.