GET /nest/passphrase

Overview

The /nest/passphrase endpoint generates 7-character entry keys that allow users to claim (link) devices to their accounts. The device polls this endpoint during pairing to get the code it displays on-screen. A companion endpoint /nest/passphrase/status lets the device poll to find out if its entry key has been claimed.

These endpoints are part of the Device Protocol API on port 8000. They are called directly by thermostat firmware during the pairing flow.

Endpoints

GET http://your-server:8000/nest/passphrase
GET http://your-server:8000/nest/passphrase/status

Returns the current unexpired entry key for the device. If no valid key exists, a new one is generated. The device polls this endpoint repeatedly during pairing. The server returns the same key on each request until it’s claimed or expires — generating a new key on each call would invalidate the key before the user can enter it.

Request

GET /nest/passphrase HTTP/1.1
Host: your-server:8000
Authorization: Basic <base64(d.SERIAL.SUFFIX:password)>

The device serial is extracted from the Basic Auth user ID.

Response (200 OK)

{
  "value": "A3XR7M2",
  "expires": 1707234600000
}

Field	Type	Description
`value`	string	7-character alphanumeric entry key (e.g., `A3XR7M2`)
`expires`	number	Expiration timestamp in milliseconds since Unix epoch

The expires field must be a JSON number, not a string. If it is sent as "1707234600000" (a string), the device silently rejects the response and never displays the entry key. The expiration must be at least 30 minutes in the future.

Entry Key Properties

Length: 7 alphanumeric characters
Display format: The device shows the code as XXX-XXXX (e.g., A3X-R7M2)
TTL: 1 hour by default (configurable via ENTRY_KEY_TTL_SECONDS)
Reuse: The same key is returned until claimed or expired
Single-use: Can only be claimed once

Error Responses

Status	Body	Cause
`400`	`{"error": "Device serial required"}`	Missing or unparseable Basic Auth
`503`	`{"error": "Entry key service unavailable"}`	Database unavailable