Purpose of claim code

We are writing our own app to setup P1s that are part of a product. My question is, what is the purpose of a claim code? It seems like the same functionality of claiming can be done by done by posting to the /devices API?

Are claim codes just a convenience for the setup process? Or do they enable some sort of scenario that could not be handled by calling the claim API directly?

A simplistic rough picture may be:
You have three players on the scene, but only a two way communication path (since the fully established three way communication isn’t set up yet)

  • the device from which you initiate the claiming
  • the device you want to claim
  • the cloud

In order to ensure that all three parties are to be trusted even when they can’t all communicate at the same time since one of them is always left out, the initiator prepares the cloud that there will be a device requesting access to the account, for which the cloud hands out a code word (claim code).
The initiator of that safe conversation tells the third party (the device) the secret and instructs it to request access to the account by use of this code word.
At that point the only party entitled to do such critical stuff (initiator) is not part of the conversation anymore, so the code word (claim code) is the warrant that the whole process was originally authorised correctly.
Only when the device has a valid claim code known to the cloud and not expired yet, the cloud will let the device gain access to the account of the initiator.

For a more technical description look here

1 Like


What happens if you directly call https://docs.particle.io/reference/api/#claim-a-device without having a claim code? Would that not work for setting up a brand new P1 or Photon?

Yes, the claim a device API can be used instead of the claim code, as long as you know the device ID of the P1 you are claiming.

The reason for the claim code is an order of operations problem, especially on iOS. The mobile apps and device SDK don’t know the device ID of the device until it connects to the Photon/P1 private Wi-Fi configuration network. However, once you’ve connected to the Photon/P1 Wi-Fi network, you won’t have access to the Internet anymore, so you can’t make the claim a device API call from the mobile device.

The claim code allows you to make the API call before knowing the device ID and before connecting to the Photon/P1 Wi-Fi. The claim code is passed to the device, which then connects to Wi-Fi and passes the information to the cloud, which associates the device and the account that created the claim code.


Thanks. This now makes a lot of sense. I hadn’t thought through that order of operations problem where the iPhone doesn’t have internet access while connected to the Photon.

Thanks for the help @ScruffR @rickkas7!