rock/poimen-memory
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: API.md + RBAC.md with Authentik integration
Build and Push / Test (push) Successful in 4m39s
Details
Build and Push / Build and push image (push) Successful in 5m57s
Details

Browse Source 
Documentation:
- docs/API.md: Complete API reference with examples
  - All endpoints with curl examples
  - Python SDK example
  - Error responses and rate limits

- docs/RBAC.md: RBAC system documentation
  - Two-level access control explained
  - Built-in roles (admin, portfolio-agent, authenticated-user)
  - Authentik configuration guide
  - Scope mapping examples for roles/permissions
  - Troubleshooting guide

JWT Integration:
- Add 'roles' field to JwtClaims struct
- Wire roles from Authentik JWT to RBAC Claims
- API key users get 'admin' role by default

Tests:
- Add test_to_rbac_claims_with_roles
- Verify roles extraction from JWT
- 670 tests passing
This commit is contained in:
rock
2026-09-01 09:44:52 -07:00
parent 66f59057f4
commit d9a143995a
4 changed files with 907 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/mem-cli/src/http_server.rs
+35 -6
View File
@@ -123,6 +123,7 @@ fn validate_apikey(req: &HttpRequest, state: &AppState) -> Result<(JwtClaims, St
nbf: None,
permissions: Some(vec!["*".to_string()]),
groups: None,
roles: Some(vec!["admin".to_string()]), // API key gets admin role
};
Ok((claims, "apikey".to_string()))
@@ -150,6 +151,7 @@ fn extract_rate_limit_key(claims: &JwtClaims) -> String {
/// Convert JWT claims to RBAC claims for AccessGuard
fn to_rbac_claims(jwt: &JwtClaims) -> RbacClaims {
RbacClaims::new(&jwt.sub)
.with_roles(jwt.roles.clone().unwrap_or_default().iter().map(|s| s.as_str()).collect())
.with_groups(jwt.groups.clone().unwrap_or_default().iter().map(|s| s.as_str()).collect())
.with_permissions(jwt.permissions.clone().unwrap_or_default().iter().map(|s| s.as_str()).collect())
}
@@ -1519,6 +1521,28 @@ pub async fn vault_file_handler(
mod tests {
use super::*;
#[test]
fn test_to_rbac_claims_with_roles() {
let jwt = JwtClaims {
sub: "alice".to_string(),
iss: "authentik".to_string(),
aud: "memory".to_string(),
exp: i64::MAX,
iat: 0,
nbf: None,
permissions: Some(vec!["memory:read".to_string()]),
groups: Some(vec!["engineering".to_string()]),
roles: Some(vec!["authenticated-user".to_string(), "homelab-team".to_string()]),
};
let rbac = to_rbac_claims(&jwt);
assert_eq!(rbac.sub, "alice");
assert!(rbac.has_role("authenticated-user"));
assert!(rbac.has_role("homelab-team"));
assert!(!rbac.has_role("admin"));
}
#[test]
fn test_to_rbac_claims_basic() {
let jwt = JwtClaims {
@@ -1530,6 +1554,7 @@ mod tests {
nbf: None,
permissions: Some(vec!["memory:read".to_string(), "memory:write".to_string()]),
groups: Some(vec!["engineering".to_string(), "ml-team".to_string()]),
roles: Some(vec!["authenticated-user".to_string()]),
};
let rbac = to_rbac_claims(&jwt);
@@ -1552,6 +1577,7 @@ mod tests {
nbf: None,
permissions: None,
groups: None,
roles: None,
};
let rbac = to_rbac_claims(&jwt);
@@ -1631,7 +1657,7 @@ mod tests {
let guard = AccessGuard::new(Arc::new(builtin_role_provider()));
// Admin JWT
// Admin JWT with roles from Authentik
let jwt = JwtClaims {
sub: "admin-user".to_string(),
iss: "test".to_string(),
@@ -1641,8 +1667,9 @@ mod tests {
nbf: None,
permissions: Some(vec!["*".to_string()]),
groups: None,
roles: Some(vec!["admin".to_string()]),
};
let rbac_claims = to_rbac_claims(&jwt).with_roles(vec!["admin"]);
let rbac_claims = to_rbac_claims(&jwt);
// Admin can access any project
let project = ResourceMeta::new("secret-project", ResourceType::Project, "secret-project");
@@ -1657,7 +1684,7 @@ mod tests {
let guard = AccessGuard::new(Arc::new(builtin_role_provider()));
// Portfolio agent JWT
// Portfolio agent JWT with roles from Authentik
let jwt = JwtClaims {
sub: "visitor-123".to_string(),
iss: "test".to_string(),
@@ -1667,8 +1694,9 @@ mod tests {
nbf: None,
permissions: Some(vec!["memory:read".to_string()]),
groups: None,
roles: Some(vec!["portfolio-agent".to_string()]),
};
let rbac_claims = to_rbac_claims(&jwt).with_roles(vec!["portfolio-agent"]);
let rbac_claims = to_rbac_claims(&jwt);
// Can read public wiki in allowed project
let public_wiki = ResourceMeta::wiki("doc-1", "homelab")
@@ -1692,7 +1720,7 @@ mod tests {
let guard = AccessGuard::new(Arc::new(builtin_role_provider()));
// JWT with no roles
// JWT with no roles (anonymous user)
let jwt = JwtClaims {
sub: "anonymous".to_string(),
iss: "test".to_string(),
@@ -1702,8 +1730,9 @@ mod tests {
nbf: None,
permissions: None,
groups: None,
roles: None, // No roles assigned
};
let rbac_claims = to_rbac_claims(&jwt); // No roles
let rbac_claims = to_rbac_claims(&jwt);
// Cannot read anything without a role
let wiki = ResourceMeta::wiki("doc", "homelab")
crates/mem-cli/src/jwt_validator.rs
+2
View File
@@ -17,6 +17,8 @@ pub struct JwtClaims {
pub nbf: Option<i64>,
pub permissions: Option<Vec<String>>,
pub groups: Option<Vec<String>>,
/// Roles from Authentik (for RBAC)
pub roles: Option<Vec<String>>,
}
/// JWKS (JSON Web Key Set) response from Authentik
docs/API.md
+414
View File
@@ -0,0 +1,414 @@
# Memory API Reference
## Authentication
All endpoints require authentication via JWT token (from Authentik) or API key fallback.
### JWT Authentication (Recommended)
```bash
# Get token from Authentik
TOKEN=$(curl -s -X POST https://authentik.riotpiao.com/application/o/token/ \
-d "grant_type=client_credentials" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" | jq -r '.access_token')
# Use token in requests
curl -H "Authorization: Bearer $TOKEN" \
http://memory.riotpiao.com/memory/query?project=homelab&query=kubernetes
```
### API Key Authentication (Fallback)
```bash
curl -H "apikey: YOUR_API_KEY" \
http://memory.riotpiao.com/memory/query?project=homelab&query=kubernetes
```
---
## Endpoints
### Health Check
```http
GET /health
```
**Response:**
```json
{
"status": "ok",
"uptime_secs": 3600
}
```
---
### Query Memory
Search learned knowledge using semantic + hybrid search.
```http
GET /memory/query?project={project}&query={query}&limit={limit}&method={method}
```
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| project | string | Yes | Project to search in |
| query | string | Yes | Search query |
| limit | int | No | Max results (default: 10) |
| method | string | No | `semantic` or `hybrid` (default: hybrid) |
**Example:**
```bash
curl -H "Authorization: Bearer $TOKEN" \
"http://memory.riotpiao.com/memory/query?project=homelab&query=fix%20kubernetes%20port%20conflict&limit=5"
```
**Response:**
```json
{
"query": "fix kubernetes port conflict",
"project": "homelab",
"method": "hybrid",
"results": [
{
"level": "L1",
"score": 0.92,
"text": "To fix port conflicts in Kubernetes...",
"source": "troubleshooting/ports.md",
"provenance": ["session-123"]
}
]
}
```
**RBAC:** Requires `memory:read` permission. Results filtered by user's project/visibility access.
---
### Context Lookup (Three-Tier RAG)
Get contextual knowledge for tool/task with failure diagnosis.
```http
POST /memory/context
Content-Type: application/json
```
**Body:**
```json
{
"project": "homelab",
"tool": "kubectl",
"task": "debug-pod",
"scope": "tool_context",
"budget": 8192,
"failure_log": "CrashLoopBackOff: container exited with code 1"
}
```
**Example:**
```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"project":"homelab","tool":"kubectl","task":"debug-pod","budget":4096}' \
http://memory.riotpiao.com/memory/context
```
**Response:**
```json
{
"tier": 1,
"lessons": [
{
"tier": 1,
"level": "L1",
"score": 1.0,
"text": "CrashLoopBackOff usually means...",
"matched_kind": "symptom",
"seen_count": 15
}
],
"skills": [
{
"name": "diagnose-pod-failure",
"score": 0.95,
"description": "Debug Kubernetes pod crashes"
}
],
"budget": {
"limit": 4096,
"used": 2048,
"dropped": []
}
}
```
**RBAC:** Requires `memory:read` permission + project access.
---
### Ingest Records
Add new knowledge to memory.
```http
POST /memory/ingest
Content-Type: application/json
```
**Body:**
```json
{
"project": "homelab",
"ingest_id": "session-2024-01-15-001",
"source": "conversation://claude/session-123",
"records": [
{"text": "Kubernetes uses port 6443 for API server..."},
{"text": "To change the port, edit /etc/kubernetes/manifests/kube-apiserver.yaml"}
]
}
```
**Example:**
```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"project":"homelab","ingest_id":"test-001","source":"manual","records":[{"text":"Test fact"}]}' \
http://memory.riotpiao.com/memory/ingest
```
**Response:**
```json
{
"status": "accepted",
"ingest_id": "test-001",
"records_queued": 1
}
```
**RBAC:** Requires `memory:write` permission + project write access.
---
### Learn from Text
Process and learn from a block of text (chunking + embedding + synthesis).
```http
POST /memory/learn
Content-Type: application/json
```
**Body:**
```json
{
"project": "homelab",
"text": "# Kubernetes Networking\n\nKubernetes uses CNI plugins...",
"query": "What are the key networking concepts?",
"chunk_size": 2000,
"memory_budget": 4096
}
```
**Example:**
```bash
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"project":"homelab","text":"# Guide\nSome content...","query":"Summarize this"}' \
http://memory.riotpiao.com/memory/learn
```
**RBAC:** Requires `memory:write` permission + project write access.
---
### List Projects
Get all accessible projects.
```http
GET /memory/projects
```
**Example:**
```bash
curl -H "Authorization: Bearer $TOKEN" \
http://memory.riotpiao.com/memory/projects
```
**Response:**
```json
{
"projects": ["homelab", "portfolio"],
"count": 2
}
```
**RBAC:** Returns only projects user has read access to.
---
### List Skills
Get extracted skills.
```http
GET /memory/skills
```
**Response:**
```json
{
"skills": [
{
"name": "diagnose-pod-failure",
"description": "Debug Kubernetes pod issues",
"when_to_use": "Pod in CrashLoopBackOff or Error state"
}
],
"count": 1
}
```
**RBAC:** Requires `memory:read` permission.
---
### Ingest Status
Check status of an ingest job.
```http
GET /memory/ingest/{ingest_id}
```
**Example:**
```bash
curl -H "Authorization: Bearer $TOKEN" \
http://memory.riotpiao.com/memory/ingest/session-2024-01-15-001
```
**Response:**
```json
{
"ingest_id": "session-2024-01-15-001",
"status": "completed",
"records_processed": 5,
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:30:05Z"
}
```
---
## Error Responses
### 401 Unauthorized
```json
{
"error": "unauthorized",
"reason": "missing Authorization header"
}
```
### 403 Forbidden
```json
{
"error": "forbidden",
"reason": "missing capability: memory:write"
}
```
Or with RBAC:
```json
{
"error": "forbidden",
"reason": "access denied to project 'secret-project'"
}
```
### 429 Too Many Requests
```json
{
"error": "rate_limited",
"reason": "exceeded 1000 requests/hour for /memory/query"
}
```
---
## Rate Limits
| Endpoint | Limit |
|----------|-------|
| `/memory/ingest` | 100/hour |
| `/memory/query` | 1000/hour |
| `/memory/context` | 100/hour |
| `/memory/learn` | 100/hour |
Rate limits are per-user (based on JWT `sub` claim).
---
## SDK Examples
### Python
```python
import requests
class MemoryClient:
def __init__(self, base_url, token):
self.base_url = base_url
self.headers = {"Authorization": f"Bearer {token}"}
def query(self, project, query, limit=10):
resp = requests.get(
f"{self.base_url}/memory/query",
params={"project": project, "query": query, "limit": limit},
headers=self.headers
)
resp.raise_for_status()
return resp.json()
def ingest(self, project, records, source="api"):
import uuid
resp = requests.post(
f"{self.base_url}/memory/ingest",
json={
"project": project,
"ingest_id": str(uuid.uuid4()),
"source": source,
"records": [{"text": r} for r in records]
},
headers=self.headers
)
resp.raise_for_status()
return resp.json()
# Usage
client = MemoryClient("http://memory.riotpiao.com", TOKEN)
results = client.query("homelab", "kubernetes networking")
```
### curl One-Liners
```bash
# Query
curl -H "Authorization: Bearer $TOKEN" \
"http://memory.riotpiao.com/memory/query?project=homelab&query=kubernetes"
# Ingest
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"project":"homelab","ingest_id":"'$(uuidgen)'","source":"cli","records":[{"text":"New fact"}]}' \
http://memory.riotpiao.com/memory/ingest
# Context
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"project":"homelab","tool":"kubectl","task":"debug"}' \
http://memory.riotpiao.com/memory/context
```
docs/RBAC.md
+456
View File
@@ -0,0 +1,456 @@
# RBAC (Role-Based Access Control)
## Overview
The Memory system uses a hierarchical RBAC model integrated with Authentik OIDC:
```
┌─────────────────────────────────────────────────────────────┐
│ Authentik (OIDC) │
│ Issues JWT with: sub, roles, groups, permissions │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Memory API Server │
│ │
│ 1. Validate JWT │
│ 2. Check capability (memory:read / memory:write) │
│ 3. Resolve roles → load AccessRules │
│ 4. Evaluate scopes (project, visibility, owner) │
│ 5. Filter results by access │
└─────────────────────────────────────────────────────────────┘
```
## Two-Level Access Control
### Level 1: Capabilities (HTTP Layer)
Broad permissions checked at endpoint level:
| Capability | Endpoints |
|------------|-----------|
| `memory:read` | `/memory/query`, `/memory/context`, `/memory/projects`, `/memory/skills` |
| `memory:write` | `/memory/ingest`, `/memory/learn` |
| `*` | All (wildcard) |
These come from JWT `permissions` claim.
### Level 2: Resource Access (RBAC Layer)
Fine-grained access based on roles and scopes:
- **Project scope**: Which projects can user access?
- **Visibility scope**: Public only, or also private?
- **Owner scope**: Own resources only, or all?
- **Group scope**: Required group membership?
---
## Core Concepts
### Roles
A role is a named set of access rules:
```yaml
# config/roles/portfolio-agent.yaml
name: portfolio-agent
description: Public visitor access via portfolio site
rules:
- resources: [wiki, embedding]
verbs: [read, query]
scope:
projects: [homelab, rbc, aws, portfolio]
visibility: public
- resources: [conversation]
verbs: [read, write]
scope:
projects: [portfolio]
owner: self
```
### Access Rules
Each rule specifies:
| Field | Description | Example |
|-------|-------------|---------|
| `resources` | Resource types | `[wiki, embedding, conversation, skill, project]` or `["*"]` |
| `verbs` | Allowed actions | `[read, write, delete, query]` |
| `scope` | Constraints | See below |
### Scopes
| Scope | Description | Values |
|-------|-------------|--------|
| `projects` | Allowed project names | `["homelab", "portfolio"]` or `["*"]` |
| `visibility` | Document visibility | `public` or `private` (omit for both) |
| `owner` | Owner constraint | `self` (own only), `any`, or specific user ID |
| `groups` | Required groups | `["engineering", "ml-team"]` |
---
## Built-in Roles
### admin
Full access to everything:
```yaml
name: admin
rules:
- resources: ["*"]
verbs: [read, write, delete, query]
```
### portfolio-agent
Public visitor via portfolio site:
```yaml
name: portfolio-agent
rules:
# Read public wiki/embeddings from allowed projects
- resources: [wiki, embedding]
verbs: [read, query]
scope:
projects: [homelab, rbc, aws, portfolio]
visibility: public
# Manage own conversations in portfolio only
- resources: [conversation]
verbs: [read, write]
scope:
projects: [portfolio]
owner: self
```
### authenticated-user
Logged-in user via Authentik:
```yaml
name: authenticated-user
rules:
# Read all wiki/skills (including private)
- resources: [wiki, embedding, skill]
verbs: [read, query]
# Manage own conversations anywhere
- resources: [conversation]
verbs: [read, write, delete]
scope:
owner: self
```
---
## Authentik Integration
### JWT Claims
The Memory API expects these claims in JWT:
```json
{
"sub": "alice",
"iss": "https://authentik.riotpiao.com/application/o/poimen-memory/",
"aud": "poimen-memory",
"exp": 1735689600,
"permissions": ["memory:read", "memory:write"],
"groups": ["engineering", "ml-team"],
"roles": ["authenticated-user", "homelab-team"]
}
```
### Authentik Configuration
#### 1. Create Application
```
Name: poimen-memory
Slug: poimen-memory
Provider: OAuth2/OIDC
```
#### 2. Create OAuth2 Provider
```
Name: poimen-memory-provider
Client type: Confidential
Redirect URIs: https://memory.riotpiao.com/callback
Scopes: openid profile email
```
#### 3. Add Custom Scopes for Roles
Create a **Scope Mapping** to include roles in JWT:
**Name:** `memory-roles`
**Scope name:** `roles`
**Expression:**
```python
# Return user's groups that match memory roles
role_groups = ["admin", "portfolio-agent", "authenticated-user", "homelab-team"]
return {
"roles": [g.name for g in user.ak_groups.all() if g.name in role_groups]
}
```
#### 4. Add Permissions Scope
**Name:** `memory-permissions`
**Scope name:** `permissions`
**Expression:**
```python
# Base permissions for all authenticated users
permissions = ["memory:read"]
# Add write permission for specific groups
if user.ak_groups.filter(name__in=["admin", "homelab-team", "writers"]).exists():
permissions.append("memory:write")
# Admin gets wildcard
if user.ak_groups.filter(name="admin").exists():
permissions = ["*"]
return {"permissions": permissions}
```
#### 5. Assign Scope Mappings to Provider
In the OAuth2 Provider settings:
- Add `memory-roles` to **Scope Mappings**
- Add `memory-permissions` to **Scope Mappings**
#### 6. Create Groups in Authentik
| Group | Description |
|-------|-------------|
| `admin` | Full access |
| `authenticated-user` | Default for logged-in users |
| `portfolio-agent` | Service account for portfolio site |
| `homelab-team` | Team members for homelab project |
---
## Access Flow Example
### Scenario: Portfolio Visitor Queries Memory
1. **Visitor** opens portfolio site
2. **Portfolio site** authenticates with Authentik using service account
3. **Authentik** returns JWT:
```json
{
"sub": "portfolio-agent-sa",
"permissions": ["memory:read"],
"roles": ["portfolio-agent"]
}
```
4. **Portfolio site** calls Memory API:
```
GET /memory/query?project=homelab&query=kubernetes
Authorization: Bearer <jwt>
```
5. **Memory API**:
- Validates JWT ✓
- Checks `memory:read` permission ✓
- Resolves `portfolio-agent` role
- Searches homelab project
- Filters results: only `visibility: public`
- Returns filtered results
### Scenario: Authenticated User Accesses Private Docs
1. **User** logs into app via Authentik
2. **Authentik** returns JWT:
```json
{
"sub": "alice",
"permissions": ["memory:read", "memory:write"],
"groups": ["engineering"],
"roles": ["authenticated-user"]
}
```
3. **User** queries private docs:
```
GET /memory/query?project=homelab&query=internal%20secrets
```
4. **Memory API**:
- Validates JWT ✓
- Checks `memory:read` ✓
- Resolves `authenticated-user` role
- No visibility restriction → includes private docs ✓
- Returns all matching results
### Scenario: User Tries to Write Without Permission
1. **User** has read-only JWT:
```json
{
"sub": "viewer",
"permissions": ["memory:read"],
"roles": ["portfolio-agent"]
}
```
2. **User** tries to ingest:
```
POST /memory/ingest
```
3. **Memory API**:
- Checks `memory:write` permission ✗
- Returns `403 Forbidden`:
```json
{"error": "forbidden", "reason": "missing capability: memory:write"}
```
---
## Custom Roles
### Creating a Team Role
```yaml
# config/roles/ml-team.yaml
name: ml-team
description: ML team with access to ML projects
rules:
# Full access to ML projects
- resources: [wiki, embedding, skill]
verbs: [read, write, query]
scope:
projects: [ml-experiments, model-training, datasets]
# Read-only access to shared projects
- resources: [wiki, embedding]
verbs: [read, query]
scope:
projects: [homelab, documentation]
visibility: public
# Own conversations only
- resources: [conversation]
verbs: [read, write, delete]
scope:
owner: self
```
### Loading Custom Roles
Set environment variable:
```bash
RBAC_ROLES_DIR=/app/config/roles
```
Or use Kubernetes ConfigMap:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: memory-roles
data:
ml-team.yaml: |
name: ml-team
rules:
- resources: [wiki]
verbs: [read, write]
scope:
projects: [ml-experiments]
```
---
## Testing RBAC
### Check Your Access
```bash
# Decode your JWT
echo $TOKEN | cut -d. -f2 | base64 -d | jq
# Test query (should work with memory:read)
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:8080/memory/query?project=homelab&query=test"
# Test ingest (requires memory:write)
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"project":"homelab","ingest_id":"test","source":"test","records":[{"text":"test"}]}' \
http://localhost:8080/memory/ingest
```
### Verify Project Filtering
```bash
# List accessible projects
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8080/memory/projects
# Should only return projects your role can access
```
### Test Visibility Filtering
```bash
# As portfolio-agent: should only return public docs
curl -H "Authorization: Bearer $PORTFOLIO_TOKEN" \
"http://localhost:8080/memory/query?project=homelab&query=private"
# As authenticated-user: should return public + private
curl -H "Authorization: Bearer $USER_TOKEN" \
"http://localhost:8080/memory/query?project=homelab&query=private"
```
---
## Troubleshooting
### "missing capability: memory:read"
JWT doesn't have `memory:read` in `permissions` claim.
**Fix:** Update Authentik scope mapping to include `memory:read`.
### "access denied to project 'X'"
User's role doesn't allow access to that project.
**Fix:**
1. Check user's roles in JWT
2. Verify role's `scope.projects` includes the project
3. Or add user to a group with project access
### Results Missing (RBAC Filtered)
Private docs filtered out due to visibility scope.
**Check:**
1. Document visibility (public/private)
2. User's role visibility scope
3. Enable debug logging: `RUST_LOG=debug`
### No Roles in JWT
Authentik not configured to include roles.
**Fix:**
1. Create scope mapping for roles
2. Add mapping to OAuth2 provider
3. Request `roles` scope in token request
---
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `RBAC_ROLES_DIR` | Directory for YAML role files | (builtin roles only) |
| `MEM_AUTH_MODE` | `jwt` or `apikey` | `jwt` |
| `AUTHENTIK_ISSUER` | Authentik OIDC issuer URL | required for JWT |
| `AUTHENTIK_AUDIENCE` | Expected JWT audience | `poimen-memory` |
| `JWT_CACHE_TTL_SECS` | JWT validation cache TTL | `3600` |