Create Claim Code API example

Cloud
1

The API docs provide a method for returning a customer claim code.

POST /v1/device_claims

I want to use this as Step 4 in the two legged auth example, i.e. I have created a customer object and retrieved their access token. I now want to tie this customer to their new device.

The method signature does not include customer details (or device ID!), so I presume it is sent in the headers? Can someone provide an example header (if indeed this is how it is used).

There is a JS function to do this:

particle.claimDevice({ deviceId: ‘DEVICE_ID’, auth: token }).then(function(data) {
console.log(‘device claim data:’, data);
}, function(err) {
console.log(‘device claim err:’, err);
});

Again - is the auth: token the customers ‘access_token’?

@jeiden - is this something you can comment on please?

Thank you

Kevin

2

Hey @Kevin,

Sorry you’re having trouble. You’re actually using the incorrect endpoint to create the customer claim code. As discussed in the docs on generating a claim code, you should use the organization-specific endpoint for creating the claim code, which is:

POST /v1/orgs/:orgSlug/products/:productSlug/device_claims

You can find the reference docs on this endpoint here. The JS function in particle-api-js is not what you should be using to claim the device for a customer.

You will need to first generate the claim code using the endpoint above. When you hit the device claim endpoint, you should use the customer’s access token who is trying to claim the device. This will ensure that when the device comes online with the claim code, it will be associated to the right customer account.

After you have generated the claim code, you will send it to the device via SoftAP. The iOS and Android setup libraries will handle this all for you if organization mode is on. If you’re using JS to do device setup via soft-ap-setup-js, you’ll need to pass the claim code in via sap.setClaimCode().

When the device comes online with the claim code, it will be claimed to the customer’s account.

Give the docs on device setup/claiming a read to clear some of this up.

We certainly need better examples on specifically how to implement all this, which will be coming soon. Totally realize that this isn’t incredibly clear right now!

Thanks,

Jeff

5 Likes
3

Thanks for the clarification @jeiden . Would it be possible to provide a curl example so I can see how the customer access oken is passed in (I.e. What is it called in the header)?

4 
curl -X POST -H "Authorization: Bearer 1234"
https://api.particle.io/v1/orgs/test/products/test-product/device_claims
1 Like
5

Hi @jeiden. I’m also attempting to create a claim code. When I run the curl example (using my orgslug and productslug) I get “ok: false, error: Organization not found for user”

However, I can use the same orgslug and productslug to list organizations and products using curl.

Second question: Am I correct in assuming that a claim code only needs to be generated once? (And then can be used over and over in my website/app during softap to allow customers to claim their devices?)

Thanks,
Dan

6

Aha! Never mind. I reread the instructions above for the tenth time and finally saw the part where it said to use the CUSTOMER’S access_token in the GenerateClaimCode request. So that also answers my 2nd question (no).

So I was able to generate a product-related claim code for a customer and then assign it during softap. Now the customer shows in my org dashboard and the product shows as owned by that customer.

Sweet!

1 Like
7

Glad you got it figured out!

8

I got this to work using only the product info, nothing related to an organization.
Example:

curl -X POST -H “Authorization: Bearer xxxCustomerAccessCodexxx” https://api.particle.io/v1/products/[productID]/device_claims

Just in case anyone was wondering :smiley:

9

An iOS Example with Xcode 8 and Swift 3 of how this process should be configured, or an example app with some more thorough supporting documentation, would go a very long way in illustrating this process better. Thank you in advance for when you get this done. Please correct me if I am wrong here, but using Simple Auth, as it is explained, the claim code is what allows the users particle device to not only be associated with their Particle Account, but also allows for integration with the iOS App I am building, so their device can pickup custom firmware I put out for it, and also so the app can control the particle using the code written in the custom firmware and my iOS App. Assuming all that to be true, lets say I have built a connected toaster for example, and the user is in my iOS app, and there is a page there with a button on it, for them to login to their particle account through the OAuth Prompt which I have successfully displaying, and they login with their particle account, when does the claim code come into play during this process? What is the recommended way to create, retrieve, and deal with the claim code inside an iOS app? Again, this is where an example, preferably a YouTube walk though would be wonderful. I ideally want to be able to unbox a brand new particle Core or Photon, and through the login process in my app, setup its wifi and pass it the claim code, without ever having to open the particle app. Then be able to send and receive data inside my iOS app. I can get the OAuth Prompt to appear inside my app, but when it does, it always says “Sorry you must be logged in as a Particle Customer.” If I then signup for an account, I get a “Request failed: bad request (400)” error. I know I am missing some code to make the OAuth process work right, but as I cannot find any recent working example, I am stuck. Can anyone help me work through this issue, please???

10

Hi @jeiden,

I’m not able to generate claim after updating access token. When I try to generate a claim_code using URL https://api.particle.io/v1/products/xyz/device_claims?access_token=xyz, I’m getting the following errors:

“Organization not found for user.”

The new access_token was generated using URL https://api.particle.io/oauth/token

But the old access_token is working and the device is getting claimed.

11

@mukesh,

Double check that your access token was either:

  • Generated by a Particle user that is part of the product team
  • Generated using OAuth client credentials that were created under the product

Hope this helps,

Jeff