> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nolongerevil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)

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

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.

```bash theme={null}
# 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

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

### Getting a Hosted API Key

1. Go to [https://nolongerevil.com/settings](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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://nolongerevil.com/api/v1/devices \
    -H "Authorization: Bearer nle_your_api_key_here"
  ```

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

  ```python Python theme={null}
  import requests
  response = requests.get(
      'https://nolongerevil.com/api/v1/devices',
      headers={'Authorization': 'Bearer nle_your_api_key_here'}
  )
  ```
</CodeGroup>

### API Key Scopes

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

<AccordionGroup>
  <Accordion title="How are hosted API keys stored?" icon="database">
    Keys are hashed using SHA-256 before storage. The plaintext key is never stored — only the hash.
  </Accordion>

  <Accordion title="What if my hosted key is compromised?" icon="shield-exclamation">
    Immediately revoke it in Settings → API Keys, then generate a new key and update your applications.
  </Accordion>
</AccordionGroup>

***

## 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)   |