API Key Management

Learn how to generate, manage, and use API keys to authenticate with the Lelu Authorization Engine.

Overview

Lelu uses API keys for authentication. Each API key is associated with a tenant and environment (test or live). Keys are stored securely in Redis and can be revoked at any time.

Key Formats

Getting API Keys

Option 1: Anonymous API Key (Recommended for Testing)

The fastest way to get started! Visit the API key page to generate an anonymous API key instantly:

• ✅ No registration or email required
• ✅ Instant generation (under 5 seconds)
• ✅ 500 requests per day
• ✅ Perfect for testing and development
• ✅ 30-day expiration (extends with use)

Option 2: Using PowerShell Script (Self-Hosted)

For self-hosted deployments, we provide a convenient PowerShell script that generates a key and stores it in Redis automatically.

# Run the generation script
./generate-api-key.ps1

# The script will:
# 1. Generate a secure random API key
# 2. Store it in Redis
# 3. Update your .env file
# 4. Display the key for immediate use

Method 2: Using Redis CLI

You can manually create keys using the Redis CLI if needed.

# Generate a random key (use your preferred method)
$randomBytes = New-Object byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($randomBytes)
$randomPart = [Convert]::ToBase64String($randomBytes).Replace('+','-').Replace('/','_').TrimEnd('=')
$apiKey = "lelu_test_$randomPart"

# Store in Redis
docker exec lelu-redis redis-cli SET "lelu:apikey:$apiKey" '{"tenant_id":"your_tenant","key_id":"key123","created_at":"2026-03-27T00:00:00Z","revoked":false,"name":"My Key","env":"test"}'

Method 3: Anonymous API Keys

For testing, you can generate anonymous keys through the web UI at /api-key. These keys:

• Expire after 30 days
• Are IP-bound on first use
• Have rate limits (5 per hour, 10 per day per IP)
• Don't require account creation

Using API Keys

HTTP Header Authentication

Include your API key in the X-API-Key header with every request:

# PowerShell
Invoke-WebRequest -Uri "http://localhost:8083/v1/authorize" \
  -Headers @{"X-API-Key"="lelu_test_YOUR_KEY_HERE"} \
  -Method POST \
  -Body '{"principal":{"id":"user_123"},"resource":{"type":"document"},"action":"read"}'

# cURL
curl -H "X-API-Key: lelu_test_YOUR_KEY_HERE" \
  -X POST http://localhost:8083/v1/authorize \
  -d '{"principal":{"id":"user_123"},"resource":{"type":"document"},"action":"read"}'

SDK Configuration

When using the SDKs, set the API key in your environment or configuration:

import { LeluClient } from '@lelu/sdk';

const client = new LeluClient({
  baseUrl: 'http://localhost:8083',
  apiKey: 'lelu_test_YOUR_KEY_HERE'
});

from auth_pe import LeluClient

client = LeluClient(
    base_url="http://localhost:8083",
    api_key="lelu_test_YOUR_KEY_HERE"
)

import "github.com/lelu/sdk/go"

client := lelu.NewClient(lelu.Config{
    BaseURL: "http://localhost:8083",
    APIKey:  "lelu_test_YOUR_KEY_HERE",
})

Testing Your API Key

Use the provided test script to verify your API key works correctly:

# Test with default key from .env
./test-api-key.ps1

# Test with specific key
./test-api-key.ps1 -ApiKey "lelu_test_YOUR_KEY_HERE"

Key Management

Listing Keys for a Tenant

# List all keys in Redis
docker exec lelu-redis redis-cli KEYS "lelu:apikey:*"

# Get key metadata
docker exec lelu-redis redis-cli GET "lelu:apikey:lelu_test_YOUR_KEY"

Revoking Keys

To revoke a key, update its metadata to set revoked: true:

# Get current metadata
$metadata = docker exec lelu-redis redis-cli GET "lelu:apikey:lelu_test_YOUR_KEY"

# Update to revoked (modify the JSON)
$revokedMetadata = $metadata -replace '"revoked":false', '"revoked":true'

# Store updated metadata
docker exec lelu-redis redis-cli SET "lelu:apikey:lelu_test_YOUR_KEY" $revokedMetadata

Deleting Keys

# Permanently delete a key
docker exec lelu-redis redis-cli DEL "lelu:apikey:lelu_test_YOUR_KEY"

Security Best Practices

Troubleshooting

Error: "unauthorized: invalid or missing API key"

This error occurs when:

• No API key is provided in the request
• The API key format is invalid
• The key doesn't exist in Redis
• The key has been revoked

Solution: Verify your key exists in Redis and is not revoked. Generate a new key if needed.

Error: "rate limit exceeded"

Anonymous keys have rate limits. If you hit the limit, wait for the time window to reset or use a regular API key.

Redis Connection Issues

Ensure Redis is running and accessible:

# Check Redis status
docker-compose ps redis

# Test Redis connection
docker exec lelu-redis redis-cli PING

Next Steps

• Quickstart Guide - Get started with your first authorization request
• API Reference - Learn about all available endpoints
• Audit Trail - Monitor API key usage
• Get API Key - Generate anonymous keys without signup