Skip to main content

​
Overview

The No Longer Evil API uses API key authentication with Bearer tokens. All requests must include a valid API key in the Authorization header.

Secure

SHA-256 hashed keys with one-time display on generation

Scoped

Granular permissions with read and write scopes

​
API Key Authentication

All API requests require authentication using an API key. Keys are managed through the Settings page and support granular permissions.

​
Getting an API Key

  1. Navigate to Settings: Go to https://nolongerevil.com/settings
  2. Click API Keys tab: Access the API key management interface
  3. Generate New Key: Click “Generate New Key”
  4. Configure the key:
    • Name: Descriptive name (e.g., “Home Assistant”, “Python Script”)
    • Scopes: Select read, write, or both
      • read: View device status and settings
      • write: Control devices (temperature, mode, fan, etc.)
  5. Copy the key immediately: The full key is shown only once!
API keys are shown only once when generated. Store them securely - you cannot retrieve them later. The key starts with nle_ followed by 64 hexadecimal characters.

​
API Key Format

API keys follow this format: 
nle_abc123def456... (64 hex characters after nle_)
Example: nle_012e7ffdd4ac7b83848c849c8417d8b632f076c2c10e63ebf69aae3f16b9a914

​
Using Your API Key

Include the API key in the Authorization header as a Bearer token: 
curl https://nolongerevil.com/api/v1/devices \
  -H "Authorization: Bearer nle_your_api_key_here"

​
API Key Scopes

Scopes control what actions an API key can perform:
ScopeDescriptionExample Endpoints
readView device status and settingsGET /devices, GET /thermostat/{id}/status
writeControl devicesPOST /thermostat/{id}/temperature, POST /thermostat/{id}/mode
Best practice: Create separate API keys for different integrations with minimum required scopes. For example, a monitoring dashboard only needs read scope.

​
Device Restrictions

When creating an API key, you can optionally restrict access to specific devices:
  • No restrictions (default): Access all devices you own or have shared access to
  • Specific devices: Limit access to selected device serial numbers only
This is useful for:
  • Sharing access with third parties for specific devices
  • Creating keys for specific rooms or zones
  • Limiting scope of potentially compromised keys

​
Security Best Practices

API keys are hashed using SHA-256 before storage. The server never stores the plaintext key - only the hash is kept in the database. This means even if the database is compromised, the actual keys cannot be recovered.
  1. Immediately revoke the compromised key in Settings → API Keys
  2. Generate a new key with the same or different permissions
  3. Update your applications with the new key
The old key stops working immediately upon revocation.
Yes! Best practice is to rotate API keys periodically:
  1. Generate a new key with the same permissions
  2. Update your applications to use the new key
  3. Monitor usage of the old key (check “last used” timestamp)
  4. Once confirmed the old key is unused, revoke it
API keys support optional expiration dates. When creating a key, you can set it to expire after a certain period. This is useful for:
  • Temporary access grants
  • Time-limited integrations
  • Compliance requirements
Expired keys are automatically rejected with a 401 Unauthorized response.

​
Rate Limiting

API keys are subject to rate limiting to protect the service:
Authentication TypeLimitWindow
User accounts (Clerk)100 requestsPer minute
API keys20 requestsPer minute

​
Rate Limit Headers

All API responses include rate limit headers: 
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 2025-01-24T12:34:56.000Z

​
Rate Limit Exceeded

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": "Rate limit exceeded",
  "retryAfter": "2025-01-24T12:35:00.000Z"
}
Monitor the X-RateLimit-Remaining header to track your usage and avoid hitting the limit.

​
Common Errors

​
401 Unauthorized

{
  "error": "Unauthorized"
}
Causes:
  • Missing API key in Authorization header
  • Invalid or expired API key
  • Malformed Authorization header
Solution: Verify your API key is correct and formatted as Authorization: Bearer nle_your_api_key_here

​
403 Forbidden

{
  "error": "Access denied to this device"
}
Causes:
  • API key doesn’t have permission to access the device
  • Device serial not in API key’s allowed devices list
  • Insufficient scope (e.g., write action with read-only key)
Solution: Check your API key permissions in Settings → API Keys

​
Summary

FeatureDetails
Authentication MethodAPI key with Bearer token
Key Formatnle_ + 64 hex characters
StorageSHA-256 hashed, never stored in plaintext
Scopesread (view) and write (control)
Rate Limits20 req/min (API keys), 100 req/min (user accounts)
ExpirationOptional, configurable per key
TrackingLast used timestamp

​
Next Steps

Get an API Key

Create your first API key

List Devices

Make your first API request

Set Temperature

Control your thermostat

API Introduction

Learn about the API