Appearance
IAM — Device Pairing
A pairing is a link between a device and one owner — an account, a device group or a role. The policy.target on the caller's .pair rules names the owners a claim may land on, and there is no default: a grant naming none claims the device into the tenant and pairs it nowhere.
Pairing to an account also writes a rule onto it naming that one device — a group or a role reaches devices through a .devices rule, an account has none — and unpairing takes it away again. Claiming an unassigned device re-keys it into the tenant (REGISTER_DEVICE_REKEY); links are published as DEVICEGROUP_LINK_DEVICE and DEVICEGROUP_UNLINK_DEVICE.
| POST | Claim and pair a device/api/v1/pair |
| DELETE | Unpair a device/api/v1/pair |
Claim and pair a device
Names the device by exactly one of deviceResourceIdentifier, imei or iccid, with the printed claim code as the proof of possession. Where the device lands is decided by the caller's pair grant and never by the body; a device belonging to another tenant is refused, and pairing is additive — one device may end up with several owners.
POST
/api/v1/pairBody
| Name | Description |
|---|---|
deviceResourceIdentifierstringoptional | Names the device by its CRN. Exactly one of deviceResourceIdentifier, imei or iccid may be sent — two identifiers that disagree are refused rather than reconciled. |
imeistringoptional | The device's IMEI, the 15-digit identity of its modem. max length 16 Pattern: ^[0-9a-fA-F]+$ |
iccidstringoptional | ICCID of the device's SIM, hexadecimal, at most 20 characters. It is printed on the SIM and therefore public: it names a device but proves nothing about it. max length 20 Pattern: ^[0-9a-fA-F]+$ |
claimCodestring | The claim code printed on the device, base58 and case-sensitive; the dashes of the printed XXXX-XXXX-XXX grouping are dropped before it is compared. Pairing takes it as the proof of physical possession, and a device listing carries it only for a reader outside any tenant. |
Response
| Name | Description |
|---|---|
resourceIdentifierstring | Unique Coldwave resource name (CRN) that identifies a resource |
Errors
| Status | Description | Body |
|---|---|---|
403 | You do not have permission to perform this action | |
404 | No device matches the reference, the claim code does not belong to it, or — when unpairing — no owner the caller may reach holds it. Check the identifier against the label on the device and the code as it is printed. | |
409 | The claimed device belongs to another tenant. Re-claiming one already in the caller's tenant is fine; a device in a foreign tenant has to be moved there first. | code: DEVICE_TENANT_CONFLICT |
400 | The request did not match the schema for this endpoint. The details field carries the specific failures. | error: Validation Error |
401 | No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key. | error: string |
500 | The request failed for a reason that is not the caller's to fix. Safe to retry. | error: string, message: string, statusCode: 50 |
Unpair a device
Needs no claim code: the caller's own pair grant says which owners a device may be taken away from, and only those are unlinked, so another group keeps it. A device no reachable owner holds reads as not found, exactly like one in another tenant.
DELETE
/api/v1/pairBody
| Name | Description |
|---|---|
deviceResourceIdentifierstringoptional | Names the device by its CRN. Exactly one of deviceResourceIdentifier, imei or iccid may be sent — two identifiers that disagree are refused rather than reconciled. |
imeistringoptional | The device's IMEI, the 15-digit identity of its modem. max length 16 Pattern: ^[0-9a-fA-F]+$ |
iccidstringoptional | ICCID of the device's SIM, hexadecimal, at most 20 characters. It is printed on the SIM and therefore public: it names a device but proves nothing about it. max length 20 Pattern: ^[0-9a-fA-F]+$ |
Errors
| Status | Description | Body |
|---|---|---|
403 | You do not have permission to perform this action | |
404 | No device matches the reference, the claim code does not belong to it, or — when unpairing — no owner the caller may reach holds it. Check the identifier against the label on the device and the code as it is printed. | |
400 | The request did not match the schema for this endpoint. The details field carries the specific failures. | error: Validation Error |
401 | No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key. | error: string |
500 | The request failed for a reason that is not the caller's to fix. Safe to retry. | error: string, message: string, statusCode: 50 |