Confusing documentation around API Users (vs oAuth client) - Access Tokens

Cloud
1
  1. I started at Getting Started - API Users.

Where it appears to me the best suggested approach is indeed to create an API User.

You click the link there and you are taken to Reference - API Users.

As you read through you see a API User Tutorial link, and you think, cool, this must be it.

That tutorial takes you back to a different section of the Getting started guide. It shows some examples that seem to have nothing to do with API users, (no instructions on how to create them in the supposed tutorial, that's off) shows something about creating an OAuth Client. One can mistakenly assume here then that API Users are probably created by an OAuth Client. But then you get some form of weird warning:

Create a product bearer token

The client secret is not an access token! In order to use most product APIs, you will either need to use your own account token, or a product-specific token.

By this point you are so lost in an API, Authentication and Access Token spaghetti of documentation you are probaly bound to get lost as I did for the next 3 hours trying to make sense of it all.

oAuth Clients (product bearars) are scoped to either and Org or a product, as are APU users, and with both it seems you do a one time creation. But then there is only a UI tool for creating an oAuth Client.

And most confusingly of all, the getting started supposedly "API User" tutorial, walks you through creating an oAuth User to run the tutorial?

I am posting this out of sheer benevolence in trying to help other new developers get lost as I did in this topic.

Also at then end of they day, it seems it's marginally different to create a non-expiring access token though an API User creation request (no UI too, at the end the only way to create an API User is through a API call with an already existing token you had to generate through some other mechanism. Than to create a non-expiring OAuth access token ( you had to create a token anyways to be able to create an API User, might as well stop at the first one you create). Manually one-time creating not one, but two auth tokens just feels like too much.

2

The paragraph under API users is what you really need:

An API User Account is a specific type of user account in the Particle platform that is designed to replace using 'human' accounts for programmatic tasks. You can configure them in the console.

There used to be a whole section on manually creating API users using the API, or using the tool in the docs, which is no longer needed because you can just create API users from the console.

The main reason for API users is that you can control specifically which APIs the token has access to. Product bearer tokens only have access to a subset of APIs, and you can't choose which ones.

1 Like