Learn how to authenticate with the Lightfast Memory API and manage API keys securely.
API Keys
All API requests must include an API key in the Authorization header:
bash
Authorization: Bearer lf_sk_live_abc123...Key Types
Secret Keys
Secret keys (lf_sk_*) provide full access to the API and should only be used in server-side applications.
typescript
// ✅ Server-side (Node.js, Python backend, etc.)
const memory = createMemory({
apiKey: process.env.LIGHTFAST_SECRET_KEY // lf_sk_*
})typescript
// ❌ NEVER use secret keys in client-side code
// This exposes your key to anyone who inspects the code
const memory = createMemory({
apiKey: 'lf_sk_live_abc123...' // DANGER!
})Publishable Keys
Publishable keys (lf_pk_*) provide read-only access and can be safely used in client-side applications.
typescript
// ✅ Client-side (React, Vue, browser JavaScript)
const memory = createMemory({
apiKey: process.env.NEXT_PUBLIC_LIGHTFAST_KEY // lf_pk_*
})
// Can only perform searches, not writes
const results = await memory.searchMemory({
query: 'user query'
})Restricted Keys
Restricted keys (lf_rk_*) provide custom scoped access for specific use cases.
json
{
"scopes": [
"memory:read:github-*", // Read any GitHub collection
"memory:write:discord-123456", // Write to specific Discord
"memory:delete:linear-team-eng" // Delete from Linear
],
"collections": ["github-lightfast", "discord-123456"],
"rateLimit": "1000/hour",
"expiresAt": "2025-12-31T23:59:59Z"
}Managing API Keys
Generate Keys
Create new API keys from the Lightfast dashboard:
- Navigate to Settings → API Keys
- Click "Create New Key"
- Select key type and permissions
- Copy the key immediately (it won't be shown again)
Rotate Keys
Regularly rotate keys for security:
typescript
// 1. Generate new key in dashboard
// 2. Update your environment variables
// 3. Deploy with new key
// 4. Revoke old key after verification
// Use environment variables for easy rotation
const memory = createMemory({
apiKey: process.env.LIGHTFAST_API_KEY
})Revoke Keys
Immediately revoke compromised keys:
- Go to API Keys dashboard
- Find the compromised key
- Click "Revoke"
- Generate a new key if needed
Environment Variables
Node.js / Next.js
bash
# .env.local
LIGHTFAST_API_KEY=lf_sk_live_abc123...
# For client-side (Next.js)
NEXT_PUBLIC_LIGHTFAST_KEY=lf_pk_live_xyz789...typescript
// Server-side
const apiKey = process.env.LIGHTFAST_API_KEY
// Client-side (Next.js)
const publicKey = process.env.NEXT_PUBLIC_LIGHTFAST_KEYPython
bash
# .env
LIGHTFAST_API_KEY=lf_sk_live_abc123...python
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("LIGHTFAST_API_KEY")Docker
dockerfile
# Dockerfile
ENV LIGHTFAST_API_KEY=${LIGHTFAST_API_KEY}bash
# Run with environment variable
docker run -e LIGHTFAST_API_KEY=lf_sk_live_abc123... myappSecurity Best Practices
Never Commit Keys
Add API keys to .gitignore:
bash
# .gitignore
.env
.env.local
.env.production
*.envUse Environment Variables
Always load keys from environment:
typescript
// ✅ Good
const apiKey = process.env.LIGHTFAST_API_KEY
// ❌ Bad
const apiKey = 'lf_sk_live_abc123...'Restrict Key Permissions
Use the minimum permissions needed:
- Client apps: Use publishable keys (read-only)
- CI/CD: Use restricted keys with specific scopes
- Production: Use secret keys only on secure servers
Monitor Key Usage
Check your API key usage regularly:
- Review usage in the dashboard
- Set up alerts for unusual activity
- Audit logs for sensitive operations
Implement Request Signing
For additional security, sign requests:
typescript
import crypto from 'crypto'
function signRequest(payload: string, secret: string) {
return crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex')
}
// Include signature in request
const signature = signRequest(JSON.stringify(data), apiKey)
headers['X-Signature'] = signatureOAuth Integration
For user-specific access, integrate with OAuth providers:
GitHub OAuth
typescript
// Users authenticate with GitHub
const githubToken = await getGitHubOAuthToken()
// Use token for GitHub-specific collections
const memory = createMemory({
apiKey: process.env.LIGHTFAST_API_KEY,
auth: {
github: githubToken
}
})
// Can now access private repos the user has access to
const results = await memory.searchMemory({
collections: ['github-private-repo']
})Discord OAuth
typescript
// Users authenticate with Discord
const discordToken = await getDiscordOAuthToken()
// Use token for Discord-specific collections
const memory = createMemory({
apiKey: process.env.LIGHTFAST_API_KEY,
auth: {
discord: discordToken
}
})IP Allowlisting
Restrict API key usage to specific IPs:
json
{
"apiKey": "lf_sk_live_abc123...",
"allowedIPs": [
"203.0.113.0/24", // Office network
"198.51.100.42", // Production server
"2001:db8::/32" // IPv6 range
]
}Rate Limiting by Key
Different key types have different rate limits:
| Key Type | Requests/min | Requests/hour |
|---|---|---|
| Secret | 1000 | 30,000 |
| Publishable | 100 | 3,000 |
| Restricted | Custom | Custom |
Troubleshooting
Invalid API Key
json
{
"error": "authentication_failed",
"message": "Invalid API key"
}Solutions:
- Check key is correct and not truncated
- Verify key hasn't been revoked
- Ensure proper
Bearerprefix in header
Insufficient Permissions
json
{
"error": "permission_denied",
"message": "Key does not have write access"
}Solutions:
- Use secret key for write operations
- Check restricted key scopes
- Verify collection access permissions
Rate Limit Exceeded
json
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Retry after 42 seconds."
}Solutions:
- Implement exponential backoff
- Upgrade to higher tier
- Use request batching