Authentication

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

Go to https://nolongerevil.com/settings
Click the API Keys tab
Click Generate New Key
Select scopes: read and/or write
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 https://nolongerevil.com/api/v1/devices \
  -H "Authorization: Bearer nle_your_api_key_here"

const response = await fetch('https://nolongerevil.com/api/v1/devices', {
  headers: { 'Authorization': 'Bearer nle_your_api_key_here' }
});

import requests
response = requests.get(
    'https://nolongerevil.com/api/v1/devices',
    headers={'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)

Overview

Self-Hosted Control API

Device Protocol API

Hosted Service API

Overview

Self-Hosted: Control API (Port 8082)

Optional: API Key Auth (via Reverse Proxy)

Self-Hosted: Device Protocol (Port 8000)

Hosted Service: API Key Authentication

Getting a Hosted API Key

API Key Format

Using a Hosted API Key

API Key Scopes

Summary

​Overview

​Self-Hosted: Control API (Port 8082)

​Optional: API Key Auth (via Reverse Proxy)

​Self-Hosted: Device Protocol (Port 8000)

​Hosted Service: API Key Authentication

​Getting a Hosted API Key

​API Key Format

​Using a Hosted API Key

​API Key Scopes

​Summary

Overview

Self-Hosted: Control API (Port 8082)

Optional: API Key Auth (via Reverse Proxy)

Self-Hosted: Device Protocol (Port 8000)

Hosted Service: API Key Authentication

Getting a Hosted API Key

API Key Format

Using a Hosted API Key

API Key Scopes

Summary