Sending Claim Code to Device

Cloud
1

Hi all

Is anyone able to help out with how to send a ‘claim code’ to a device.
I’ve basically finished my web app with softap setup etc. and thought it was working ok, but I tried creating a test customer with a new account (simple auth) and realised that I was missing out the “Create Claim Code & Send to Device” step outlined here: https://docs.particle.io/guide/how-to-build-a-product/authentication/

Creating the claim code seems easy enough via the API but how should this be sent to the device? Is there an API command to do this after the device has come online?

Originally I thought it was as simple as logging the user in and claiming the device by sending their access token and device ID, so I’m a bit confused about sending a claim code through first.

The docs say this will be handled by an SDK in the future but I really need to get this sorted soon, as I’m sending out product in a few weeks. I’m a bit confused as there seems to be a lot of people already sending products to customers. How are they managing here?

Are you able to shed any light on this @jeiden?

2

@G65434_2 are you wanting to do this via JavaScript in a browser or via a native iOS or Android app?

3

From what I remember, you were working on a web app. Have you tried this: https://github.com/spark/softap-setup-js#setting-the-devices-claim-code?

There is a method for sending a claim code to a device.

1 Like
4

Thanks @jeiden

I actually had no idea there was an official Particle softAP library now.
I had been using a library created by one of the other Particle users. I’ll take a look at this now!

EDIT: Seems like it’s been there for quite a while, not sure what I was up to…

5

@G65434_2
Were you able to claim the device to the customer? I’d like to know if you had any gachas in the process.

6

Hi there, yip I’ve managed to claim customer devices. What in particular are you having trouble with?

7

It seems to mostly work for me too, but no cigar yet.

  1. I see the customer created and device ID listed in the customer record, but no customer reference or “Unclaim Device” link in device list for the same ID

  2. I want customers to be free to re-use account with vanilla Particle, other organizations and other products. Not quote sure how this is going to play out. Has to be separate oAuth login endpoints/methods, but I couldn’t find anybody reporting success in that

  3. Password reset for customers is still a mystery. Also unable to cleanup customer records/tokens

  4. Not clear about device claim. Do we still need to do that after device with configured claim code reconnects to WiFi after SoftAP or is it for brand new chips? I never seem to be able to fully unclaim the device that was at least once associated with any user anyway.

@jeiden ?

I’ll pay it forward by sharing the code once I get it all sort out.

8

Hey @sparkly, the first thing I’d recommend you doing is to read the documentation on Authentication & Security. It outlines everything you need to know about how claiming works and the product creator architecture.

The main thing to understand here is that users are different than customers. The differences between the organization and the developer architecture is discussed here.

I’ll try and answer your specific questions:

  1. If the device is in fact owned by a customer, you should be able to go to your Devices page, find the device and click to expand, then click “Unclaim Device.” This is on the Devices page, not the Customers page.

  2. Customers are scoped to an organization, therefore the account cannot be reused across organizations. They can be reused across products within an organization. It seems like you are looking for the “Login with Particle” authentication method, which is described here. This auth method is not yet available as very few people have expressed interest in it.

  3. Password resetting for customers is possible, but just isn’t super well-documented. If you click on the Settings icon for your product in the dashboard, you can configure SMTP credentials to send an password reset email to your customers.

  4. Claiming devices applies for any device that does not have an owner, not just brand new modules. You can read more about the specifics in the product creator guide

9

Thank @jeiden you for the links and answers.
It's understandable but I wouldn't say that documentation is at "everything you need to know" stage.
Back to the specifics:

  1. Yes, the fact that there is no customer association in devices view and no "Unclaim Device" link should suggest that the device is not claimed. However, I'm unable to claim that same device it with "Permission denied" message. Also same device ID appears in customers view which makes things confusing. From what I read, having the device in possession and performing the claiming process with claim token should override whatever previous ownership was, but it's not working for me. Any help is much appreciated, I can PM device info etc.

  2. Is there a parameter or separate login endpoint for customers of specific organization? Say customer of my organization purchases particle based product from another organization and uses their (same) email to create the new account with that other organization. What is going to happen?

  3. I found the SMTP setup page, thanks. Now with that configured, what needs to be done to initiate the process from the web application? I'm interested in organization specific process if different.

  4. Ok, so with the setup process takes care of claiming and there is no need to claim device at the end. Correct? Now when it comes to previously claimed units, according to this post by @zachary quote:

More importantly, if you have a Photon in your possession, and it is claimed by someone else, you just need to perform setup to claim the device. If you are borrowing the device from a friend, you can claim it from your friend, and then when you give it back, the friend can simply claim it again.

I should be able to claim device eve if it has an owner as long as it is in my possession, yet I'm not getting units reassigned to a new owner in the setup process. Any advice?

10

Hey @sparkly,

You are spot on. Our docs need to be improved, and with more examples. This is something I hope to get to internally shortly. I would also encourage anyone in the community who has successfully implemented this to contribute to the docs! My hope is to bring more clarity to this process soon. I apologize for the confusion.

  1. Yes, can you please PM the device ID?

  2. Nope, customers use the same endpoint for login as users do! POST /oauth/token. This will return a customer access token. How you hit this endpoint just depends on which authentication method you use. If you are using two-legged auth with shadow customers that do not have a password (just a username), your server will generate a scoped access token for that customer with the following request (docs):

$ curl -u my-org-client-1234:long-secret -d grant_type=client_credentials -d scope=customer=jane@example.com https://api.particle.io/oauth/token

If not, you can hit the endpoint like this (docs):

$ curl https://api.particle.io/oauth/token -u particle:particle -d grant_type=password -d username=joe@example.com -d password=SuperSecret

Where the username and password are the credentials of the customer

  1. Good question, this definitely isn’t well documented. You should hit the endpoint: POST /v1/orgs/:orgSlug/customers/reset_password with a param email in the body of the request. email should be set to the username of the customer. This will trigger the email to be sent with instructions on how to reset the password.

In your SMTP config, you included an email body with a {{link}}. This should be set to a URL where the customer can create a new password. I will post a link to example code here shortly.

  1. Correct, Photons operate under a “possession implies ownership” assumption. Going through the claiming process with a photon should allow you to claim it to a different account. I would need to see the device IDs to see what is going on
11

@sparkly here is some code that will be helpful to you when creating the HTML page for your customers to reset their password: https://github.com/spark/customer-password-reset

It will require you to host an HTML and JS file to ensure all works properly. Hope this is helpful!

12

Thanks @jeiden

#1 & #3 on the way to resolution
#4: I suspect the issue is related to cross organization/product transfers. I’ll provide IDs so you can research.

#2: Distinguishing the account is something you may consider implementing or documenting the process. I have several scenarios where behavior is not clear:

2.1) My early testers used vanilla :particle: accounts and now I’m ready to move them into organization. I can’t ask them to use different email address. Do they register a new account with my organization? Do they add organization devices to their existing accounts?
2.2) I had organization account with several devices, then registered vanilla :particle: account for same email just to see what happens. Lost access to devices in organization account.
2.3) Chances are that some customers of my organization will get another :particle: based products and use same email while registering the account with different organizations.

13

[Edited] Moved my question about this to its own thread here.

14

Im currently at this step as well. Im developing an Android app and am wondering how to best connect a customers device and then immediately pass that device a claim code and get it associated with that customer. The ParticleDeviceSetupLibrary seems like the obvious way to connect the device but then how do I claim it? I am currently generating customers and claim codes, but the only command I see in the Android SDK is claimDevice(deviceID). This doesnt appear to even use the claim code, am I missing something? Is there a way for my customers to claim devices they just connected without a claim code?

Thanks :smile:

I think I've figured out that by setting the AccessToken I should be able to bypass the login on the device setup. That partially worked but now I am getting an error saying the username field is null. Its discussed here:

There is sort of a fix posted there, but it sounds like jensck is trying to make a better one...