5 Easy Steps to Three-Legged OAuth in the Particle Cloud

Since Porter’s launch in October, a major, major update has been in the works. Included in this major update is a small but important change, which I consider essential to creating transparency and trust with our customers: real three-legged OAuth rather than having us pass your credentials through in order to retrieve an access token.

Our case was somewhat different than the two-legged OAuth process outlined in the complete documentation. We’re not creating end-user customers; our customers are developers with their own devices and Particle Cloud accounts.

We needed Three-Legged OAuth.

So, with IFTTT integration as an example, the help of nickjohnson’s tips from the Paricle Community, and a good read through the Authentication section of How to Build a Product, Denim & Steel wrapped up a proper Three-Legged OAuth experience for Porter.

If you’re in the same boat as us, perhaps you will find this condensed step-by-step guide useful.

YMMV: This is in no way official documentation, and not officially endorsed or supported by Particle.

Step 1: Register your Application with the Particle Cloud

First you need to register your application with the Particle Cloud. To do this, send a POST request to:

https:/api.particle.io/v1/clients

with the following body parameters:

{
“name”: APP_NAME,
“type”: “web”,
“access_token”: ACCESS_TOKEN,
“redirect_uri”: REDIRECT_URL
}

APP_NAME: What a customer will see when asked to grant access to your app.

ACCESS_TOKEN: Your own access token found under settings on https://build.particle.io/.

REDIRECT_URL: Your server OAuth endpoint.

You will receive a response like this:

{
“ok”: true,
“client”:
{
“name”: APP_NAME,
“type”: “web”,
“redirect_uri”: REDIRECT_URL,
“id”: CLIENT_ID,
“secret”: CLIENT_SECRET
}
}

Store your CLIENT_ID and CLIENT_SECRET for later use.

Step 2: Ask your Customers to Authorize With Particle

Your “Authorize with Particle” link or button should direct your customers to the following URL:

https://api.particle.io/oauth/authorize?client_id=CLIENT_ID&response_type=code&state=STATE

CLIENT_ID: This was obtained in the previous step.

STATE: This is a unique hash value you generate, which will be sent back to you from the Particle Cloud to prevent a CSRF attack.

Step 3: Listen to Your OAuth End Point

Once the customer grants access to your app, Particle will send a request to you OAuth endpoint with the following parameters:

REDIRECT_URL?code=CODE&state=STATE

REDIRECT_URL: This is the URL you specified when creating your OAuth client in Step 1.

CODE: This is the authorization code/short-lived token that you will use in Step 4 to obtain an Access Token.

STATE: Verify that this matches the STATE parameter value you generated and sent in Step 2.

Step 4: Get your Access Token

Finally, you will need to exchange your temporary token from previous step for an Access Token by sending a POST request to:

https://api.particle.io/oauth/token

with the following body parameters:

{
“grant_type”: “authorization_code”,
“client_id”: CLIENT_ID,
“client_secret”: CLIENT_SECRET,
“code”: CODE
}

CLIENT_ID: This is the Client ID you obtained when creating your OAuth client in Step 1.

CLIENT_SECRET: This was also obtained in Step 1 when creating your OAuth Client.

CODE: This is the authorization code obtained above, in Step 3.

You will receive a response like this:

{
“token_type”: “bearer”,
“access_token”: ACCESS_TOKEN,
“expires_in”: 7776000,
“refresh_token”: REFRESH_TOKEN
}

ACCESS_TOKEN: You will use this when sending requests to the Particle Cloud API.

REFRESH_TOKEN: You can save this and use it to obtain a new access token if or when the ACCESS_TOKEN above expires.

Step 5: Access The Particle Cloud

You can now use the Access Token obtained above to access the Particle Cloud on your customer’s behalf, listing devices, retrieving variables, executing functions, and watching events go by.

What About Identity?

It’s important to note that the Particle Cloud API doesn’t provide any sort of account identification information. This means that you don’t know which Particle account is being authorized and can’t correlate authorizations. The best you can do is get a list of devices that are associated with the account that provided authorization.

Login with Particle is coming soon, so fingers crossed.

What About Access Token Scope?

The Particle Cloud currently supports a couple of scopes, which are probably not relevant for the type of application described here. You can dig into them here.

Be Careful!

Remember, it is important to safeguard your Client Secret and your Access Tokens, especially since you will be obtaining unscoped tokens.

About Porter

Porter is a mobile app that gives you remote access to your Particle devices through an auto-generated, customizable UI for your Particle devices.

If you’re a Particle developer, you might just find that it will accelerate your development process. It’s available on the Google Play Store and the Apple App Store.

Particle and Particle Cloud are trademarks of Spark Labs, Inc.