HomeKit Setup Code

Overview

A HomeKit setup code is the eight-digit secret that a person gives an Apple device to pair it with a HomeKit accessory. It is printed on a label or shown on the accessory's display, and it authenticates the first pairing under the HomeKit Accessory Protocol (HAP) ¹. The same code can be delivered by machine as a setup payload, a 20-character X-HM:// string carried in a QR Code or an NFC tag, which also holds the accessory category, transport flags and a four-character setup ID ³ ⁵.

Apple publishes the setup code rules, but says the content of the payload is available only through its MFi Program ¹ ⁸. The public description of the X-HM:// layout comes from Apple's open-source ADK code and from third-party implementations ³ ²¹.

History

Apple announced HomeKit in the iOS 8 SDK on 2 June 2014, as a shared protocol with secure device pairing ¹⁴. iOS 8 became available on 17 September 2014 ¹⁵.

Building an accessory at first required an MFi licence, Apple testing and a dedicated authentication chip ¹⁷. Around WWDC in June 2017, Apple released a non-commercial version of the HAP specification, after login and acceptance of a licence ¹⁷ ¹⁸. Companies that sell or distribute accessories must still enrol in MFi ¹ ¹⁷. From iOS 11.3, accessories without an MFi chip can use software authentication ⁹, and HMAccessorySetupPayload, the app API that accepts a setup URL, has the same minimum version ⁸. The non-commercial Release R2 is dated 26 July 2019 ¹.

On 18 December 2019, Apple, Amazon, Google and the Zigbee Alliance announced the Connected Home over IP working group ¹⁶. The next day iMore reported that Apple had open-sourced parts of its ADK for prototyping non-commercial accessories, and would contribute HAP to the group while continuing to support it ¹⁹. Apple's platforms now support the Matter standard, from iOS 16.1 ⁷. The open-source ADK repository was archived on 28 October 2025, and its last commit dates from October 2021 ².

None of the sources fetched names the individuals who designed the code format.

Technical specification

Carriers. The eight digits can be read by a person, or the payload can be scanned from a QR code ¹ ³. Programmable NFC tags can also advertise the payload: the ADK requires an NDEF-capable tag of Type 2 or greater that supports a 30-byte payload ⁵.

Setup code

Format. Eight digits shown as XXXXXXXX; Apple's example is 10148005. SRP verifier generation must use the dashed form, here 101-48-005 ¹.
Dynamic codes. An accessory that generates codes must make a new one each time, from a cryptographically secure random number generator ¹. The ADK refreshes a displayed code every 5 minutes ⁶.
Static codes. An accessory that cannot generate codes needs a random code per unit, generated securely at manufacture. It stores an SRP verifier rather than the raw code ¹. In the ADK, the raw code is deployed only for a programmable NFC tag ⁵.
Not derived from public data. Codes must not come from a serial number, date, MAC address or similar information ¹.
Forbidden values. All-identical digits, 12345678 and 87654321 must not be used ¹. The ADK's validator enforces these same three rules ³.

Pairing

The setup code drives Pair Setup, which uses Stanford's Secure Remote Password protocol with SHA-512 and the 3072-bit group of RFC 5054 ¹. Apple's platform security guide confirms 3072-bit SRP, then ChaCha20-Poly1305 with HKDF-SHA-512 derived keys, and adds that MFi certification is verified during setup ⁹. After more than 100 unsuccessful authentication attempts, an accessory must refuse with a MaxTries error ¹. This limits online guessing of a code space of about 100 million values.

The `X-HM://` setup payload

Apple's ADK builds the payload in three parts ³:

Part	Length	Content
Prefix	7	`X-HM://`
Packed value	9	Base-36, alphabet `0`-`9` then `A`-`Z`, filled from the end
Setup ID	4	`0`-`9` and uppercase `A`-`Z`; `0000` when no ID is given

The packed value holds these fields ³:

Bits	Field	Value
45-43	Version	0
42-39	Reserved	0
38-31	Accessory category	8 bits
30	Not set by the ADK	0
29	BLE supported	flag
28	IP supported	flag
27	Paired	flag
26-0	Setup code	digits read as a decimal number

Independent implementations agree on these positions: esp-homekit ²⁴, HAP-python ²⁵, HAP-NodeJS ²⁸ and hkuri ³¹.

Paired state. The paired flag applies only to programmable NFC tags. A paired payload must carry no setup code or setup ID ⁴, and the ADK then always builds a non-pairable form ⁶.
Flag names disagree. Third-party tools call bit 30 WAC or IP_WAC ²⁴ ³¹. HomeSpan's documentation calls bit 27 NFC rather than paired, and says the Home app does not appear to use the flags ²¹. Apple's ADK is the better source here, but it does not define bit 30.
Word size. HomeSpan calls this a 45-bit word, although its own bit numbering spans 46 bits ²¹. esp-homekit counts 46 ²⁴.
Version and reserved. According to HomeSpan, the Home app does not recognise a code unless these are zero, and uses the category only for display ²¹. This comes from hobbyist testing, not from Apple.
Longer strings. A commenter on a 2018 reverse-engineering gist reported in August 2023 that a new accessory's URI was longer than this layout, and speculated the extra characters were vendor parameters ³². A parser should allow for this.

Structurally illustrative example. The packed value below uses Apple's example code 10148005 with category 5 (Lighting) ¹ and the IP flag, and was computed for this page. The setup ID ABCD is a placeholder. This does not identify any device:

value   = (5 << 31) | (1 << 28) | 10148005
payload = X-HM://00526N5B9ABCD
          |      |        |
          |      |        +-- setup ID (placeholder)
          |      +----------- 9 base-36 characters
          +------------------ prefix

Setup ID and setup hash

The setup ID is a random four-character value from a secure generator, and is required for QR displays and programmable NFC ⁵. The ADK derives a setup hash from it: SHA-512 over the setup ID followed by the device ID, truncated to 4 bytes ³ ⁴. The spec lists a matching sh Bonjour TXT key, and a 4-byte SH field in Bluetooth LE advertising data, for "enhanced setup payload information" ¹. HomeSpan says the Home app uses the setup ID to find the device on the local network after a scan ²¹. That the hash is the matching mechanism is an inference from these sources.

QR symbol parameters

Neither the public specification nor the ADK sets the QR version or error-correction level. Details of label size and placement are said to be in an MFi-only guideline titled "Setup Code Sizing and Placement" ¹².

The 20-character payload uses only characters in QR's alphanumeric mode, which includes : and / ³⁹. That mode holds 20 characters at version 1-M and 29 at version 2-Q ³⁸. The esp-homekit tool renders version 2 at level Q, and prints the eight digits beside the code in two rows of four ²⁴. This is one implementation's choice, not a documented Apple rule.

Use cases

Consumer accessories. Codes appear on the product, on labels hidden under removable parts, on packaging and in manuals. Some labels print the digits without hyphens ²⁰.
Devices with screens. The accessory generates a code and shows it on its display ¹. Home Assistant describes devices that show a new code on each pairing attempt ³³.
Tap-to-pair. Apple's instructions tell users to scan a code or hold the device near the accessory ¹³. The ADK updates a programmable tag with a pairable payload only during a time-limited NFC pairing mode ⁶.
Multipacks. Apple Home can pair every accessory in a pack from one multi-device QR code ¹³. The format of that code was not found in any public source.
Software bridges. Home Assistant's HomeKit Bridge shows a pairing QR code and PIN in its web interface ³⁴.
Hobbyist hardware. HomeSpan targets the Arduino-ESP32 platform ²², and Espressif's SDK shows a HomeKit QR code on the device at boot ²⁹.
Third-party apps. An app can pass a setup URL through HMAccessorySetupPayload, for already-deployed devices or with an ownership token ⁸. An Apple engineer has said that for HAP accessories the only way around normal pairing is an MFi-managed entitlement ¹⁰.

Implementations

Project	Lang	Stars	Last active	Notes
apple/HomeKitADK	C	~2.6k	2021-10	Apple's non-commercial reference; archived 2025-10-28 ² ³
homebridge/HAP-NodeJS	TypeScript	~2.7k	2026-10	`setupURI()` sets only the IP flag ²⁷ ²⁸
HomeSpan/HomeSpan	Arduino	~2.2k	2026-04 (release 2.1.8)	ESP32 library; default setup ID `HSPN` ²¹ ²²
maximkulkin/esp-homekit	C library, Python tool	~1.2k	2023-10	`tools/gen_qrcode` renders a label ²³ ²⁴
ikalchev/HAP-python	Python	~0.7k	2025-08	`xhm_uri()` with fixed flags value 2 ²⁵ ²⁶
espressif/esp-homekit-sdk	C	~0.7k	2026-02	Open-source SDK; commercial products need the MFi variant ²⁹
SimonGolms/homekit-code	TypeScript	94	not shown	CLI for QR labels and scannable tags ³⁰
hkuri.py gist	Python	0	2025-11	Encoder and decoder ³¹

Language entries are read from file types or project descriptions, because GitHub's language bar was not available. The hkuri gist has no stars but is listed because no dedicated decoder library was found: any QR reader recovers the string, and parsing it is a short bit-unpacking step. Home Assistant's HomeKit Device integration, built on aiohomekit, is described in terms of numeric pairing codes rather than QR codes ³³ ³⁵.

Comparison

HomeKit setup payload vs Matter QR. Matter QR strings start with the constant MT: and use a base-38 suffix of at least 19 characters from [A-Z0-9.-] ³⁶, with 11- or 21-digit manual codes ³⁷, where HomeKit has a fixed 20-character string and eight digits. Matter pairs with SPAKE2+ and device attestation, and HomeKit with SRP and an MFi check ⁹. Distribution of HomeKit accessories requires MFi enrolment, and of Matter accessories requires Connectivity Standards Alliance certification ⁷. An Apple engineer has described the two as having a similar proof-of-physical-access model, with Matter's specification being more open and Apple not enforcing it in the same way ¹⁰. Choose Matter for an accessory that must work across ecosystems, and HAP where an Apple-only design already exists.
Setup payload vs URL QR. A URL code is an ordinary link whose scheme decides how it is handled [url-ref]. X-HM:// looks like a URI, but its "host" is packed binary data, and it is meant for Apple's HomeKit setup path ³ ⁸.
Dynamic vs static code. A dynamic code changes each time and leaves no permanent secret on the label, but needs a display. A static code suits cheap devices, but can be lost: Home Assistant warns there is no way to recover a missing code ¹ ³³.

Security notes

Possession of the code is meant to show physical access. An Apple engineer has said the setup code should require some physical access to the accessory, and that the specification requires it not to be stored, accessible or derivable by the accessory itself ¹⁰. ADK's static-code flow matches this, apart from its programmable-NFC exception ⁵.

Compliance varies in practice. Home Assistant's documentation says some manufacturers ignore the specification and use a fixed or guessable code such as 123-45-678, and it warns and asks for consent before pairing with them ³³.

Fun facts

The public R2 specification never contains the string X-HM. Its references to the setup hash resolve to the unfilled placeholder ?? ?? (page ??), which suggests a section was cut from the non-commercial edition ¹. A community developer reported in 2021 that the QR format is in section 4.3 of MFi-only Release R15 ¹¹.
The forbidden code 123-45-678 is the one Home Assistant uses as its example of an insecure real-world code ¹ ³³.

Status

Active, but maintained as a private Apple specification. Apple's current developer page still offers the HAP specification, ADK and certification tools to MFi licensees ⁷, and Apple's accessory page lists products that must be "HomeKit- or Matter-enabled" ⁴⁰. Apple's support page, published 3 March 2026, still mentions HomeKit and Matter accessories ¹³. That developer page does not link a public HAP specification ⁷, and the open-source ADK is archived ². For Matter, Apple ships a certified SDK in Xcode and encourages developers to use it ⁷.

Current Apple documentation for the payload is not public: the fetched non-commercial text is a third-party copy of a 2019 release, and later revisions were not available to this research ¹ ¹¹.

Sources

Deployments

No country reports mention this standard by name.

Regions / aggregations not mapped to a single country

Universal