{"uid":"cap_uNX8dWAwB4lAU3uAV5ksI","slug":"halowerk-iot-device-hmac-sha256-authentication-f9fcdaf3","name":"Halowerk IoT Device HMAC-SHA256 Authentication","description":"Canonicalizes device_id, nonce and message, computes an HMAC-SHA256 tag with caller-supplied ephemeral key material, and optionally compares a claimed tag in constant time. It does not provision devices, store keys or replace asymmetric device identity; do not submit long-lived production secrets.","url":"https://iot.halowerk.com/v1/device-auth","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"nonce":{"type":"string","maxLength":256,"minLength":8,"description":"Fresh caller-generated challenge nonce."},"message":{"type":"string","maxLength":4096,"minLength":1,"description":"Challenge payload."},"device_id":{"type":"string","maxLength":128,"minLength":1,"description":"Stable device identifier."},"ephemeral_key":{"type":"string","maxLength":512,"minLength":16,"description":"Ephemeral HMAC key; long-lived production keys must not be sent."},"claimed_tag_hex":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.002","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.002/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.002","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_aQUfVwepVEGMzUIU3GP-Z","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.002","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Canonicalizes device_id, nonce, and message, then computes or verifies an HMAC-SHA256 authentication tag using caller-supplied ephemeral key material for IoT device challenge-response flows.","exampleAgentPrompt":"Compute an HMAC-SHA256 authentication tag for device 'sensor-42', using nonce 'a8f3c1d9e2b74056', message 'activate-pump-zone-3', and my ephemeral key 'ek_tmp_9x2mK7vQpRsLn4Yw'; also verify it against my claimed tag 'a3f1...c9d2' (full 64 hex chars).","exampleUseCases":[{"title":"IoT gateway device challenge verification","prompt":"I need to verify that sensor device 'edge-node-007' produced a valid HMAC-SHA256 tag for the challenge nonce 'b7e2a943f1c08d56' and message 'check-in-ok'. Use ephemeral key 'ek_sess_Kp2mVxNqRjLz9tYw' and compare against the claimed tag the device sent back."},{"title":"Firmware command authorization tag","prompt":"Generate an HMAC-SHA256 tag to authorize a reboot command for device 'thermostat-fl3-unit9' — use nonce 'd4c8b1e5a2f70936', message 'cmd:reboot:priority=high', and ephemeral key 'ek_cmd_3Wn7hBvXqPsLm2Tz'."},{"title":"Agent-side challenge-response during device onboarding","prompt":"I'm onboarding a new IoT device with id 'door-lock-b29' and I need to produce a challenge-response tag — nonce is 'f1a3d8c2e5b04796', the challenge message is 'onboard-handshake-v2', and the ephemeral session key is 'ek_onb_Yt6rJmKpVcNx8Qw2'."}],"resultDescription":"Returns the computed HMAC-SHA256 tag as a 64-character hex string over the canonicalized (device_id, nonce, message) tuple. If claimed_tag_hex is provided, also returns a boolean constant-time comparison result indicating whether the claimed tag matches the computed tag. Does not store keys, provision devices, or issue persistent credentials.","failureModes":["nonce shorter than 8 characters or longer than 256 characters returns a validation error","ephemeral_key shorter than 16 characters returns a key length error","claimed_tag_hex not exactly 64 hex characters returns a format validation error","message exceeding 4096 characters returns a payload size error","malformed JSON body returns a 400 parse error","missing required fields (device_id, nonce, message, ephemeral_key) returns a 422 unprocessable entity error"],"whenToPreferThis":"Choose this endpoint when you need a stateless, server-side HMAC-SHA256 computation or constant-time tag verification for IoT device challenge-response flows without managing your own crypto library. It is best suited for ephemeral session authentication where you supply short-lived key material per session — not for long-lived production secrets, asymmetric identity, or device provisioning. Prefer this over rolling your own HMAC when you need a consistent canonicalization scheme across heterogeneous IoT devices.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T05:58:54.566Z","isFirstParty":false}