Authentication

Authentication differences between the hosted service and self-hosted server

Overview

Authentication works differently depending on whether you use the hosted service or the self-hosted server.

	Hosted Service	Self-Hosted
Control API	nle_ Bearer token (required)	No auth by default
Device Protocol	HTTP Basic (device firmware)	HTTP Basic (device firmware)

---

Self-Hosted: Control API (Port 8082)

The self-hosted control API (port 8082) has no authentication by default. Any client on your network can call it without credentials.

By design, the control API is intended for use on a trusted local network. If you expose port 8082 to the public internet, you should place it behind a reverse proxy (nginx, Caddy, Traefik) that handles authentication.

# No Authorization header needed
curl -X POST http://your-server:8082/command \
  -H "Content-Type: application/json" \
  -d '{"serial": "02AB01AC012345678", "command": "set_temperature", "value": 21}'

Optional: API Key Auth (via Reverse Proxy)

If you configure a reverse proxy with HTTP Basic Auth or a Bearer token header, the control API passes those headers through unchanged. The Python server itself does not validate them.

---

Self-Hosted: Device Protocol (Port 8000)

Nest thermostats use HTTP Basic Auth on every request to the device protocol endpoints. The server extracts the device serial from the credentials — it does not validate passwords.

Authorization: Basic <base64(userid:password)>

The user ID follows the format d.{SERIAL}.{suffix}:

d.09AA01AB12345678.BC7C9039
→ serial = 09AA01AB12345678

The server accepts all credentials. This is intentional — there is no credential provisioning in the self-hosted deployment. The serial extracted from Basic Auth is used for device identification only.

---

Hosted Service: API Key Authentication

API key authentication (nle_ prefixed keys) applies to the hosted service at nolongerevil.com only. Self-hosted deployments do not use this system.

Getting a Hosted API Key

1. Go to https://nolongerevil.com/settings
2. Click the API Keys tab
3. Click Generate New Key
4. Select scopes: read and/or write
5. Copy the key immediately — it’s shown only once

API Key Format

nle_012e7ffdd4ac7b83848c849c8417d8b632f076c2c10e63ebf69aae3f16b9a914

Using a Hosted API Key

Include the key as a Bearer token:

cURL

curl https://nolongerevil.com/api/v1/devices \
  -H "Authorization: Bearer nle_your_api_key_here"

API Key Scopes

Scope	Description
read	View device status and settings
write	Control devices (temperature, mode, fan, etc.)

How are hosted API keys stored?

Keys are hashed using SHA-256 before storage. The plaintext key is never stored — only the hash.

What if my hosted key is compromised?

Immediately revoke it in Settings → API Keys, then generate a new key and update your applications.

---

Summary

Scenario	Auth Method
Calling the self-hosted control API from a script	None required
Thermostat connecting to self-hosted device protocol	HTTP Basic (serial extracted, password ignored)
Calling the hosted service API	Authorization: Bearer nle_...
Thermostat connecting to hosted service	HTTP Basic (managed by firmware provisioning)