admin (highest)
  └── editor
       └── viewer
  └── agent
       └── user (base)

from hystersis import Hystersis

client = Hystersis(api_key="admin-key")

# Read-only key
readonly_key = client.create_api_key(
    name="readonly-service",
    permissions=["memory:read", "search:read", "entity:read"],
    rate_limit={"requests_per_minute": 100},
    expires_in_days=90
)

# Agent execution key
agent_key = client.create_api_key(
    name="agent-worker",
    permissions=["memory:read", "memory:write", "skills:execute"],
    rate_limit={"requests_per_minute": 500}
)

# Admin key with full access
admin_key = client.create_api_key(
    name="admin-tool",
    permissions=["admin:all"],
    rate_limit={"requests_per_minute": 1000}
)

# Viewer key - can read but not write
curl -H "X-API-Key: readonly-key" \
  https://api.hystersis.com/memories     # ✓ 200 OK

curl -X POST -H "X-API-Key: readonly-key" \
  https://api.hystersis.com/memories     # ✗ 403 Forbidden

# Admin key - full access
curl -H "X-API-Key: admin-key" \
  https://api.hystersis.com/admin/users   # ✓ 200 OK

# Routes protected by scope
s.router.Handle("/memories", requireScope("read")(listMemories)).Methods("GET")
s.router.Handle("/memories", requireScope("write")(createMemory)).Methods("POST")
s.router.Handle("/admin/users", requireScope("admin")(listUsers)).Methods("GET")

# Create tenant-scoped key
key = client.create_api_key(
    name="tenant-abc-key",
    tenant_id="tenant_abc",
    group_id="group_xyz",
    permissions=["memory:read", "memory:write"]
)

# All requests with this key are scoped to tenant_abc
# Cannot access data from other tenants

group = client.create_group(
    name="engineering",
    policies={
        "skill_sharing_enabled": True,
        "max_memories_per_user": 10000,
        "allowed_domains": ["engineering", "code"]
    }
)

{
  "event": "api.request",
  "timestamp": "2024-01-15T10:30:00Z",
  "user_id": "user_abc",
  "role": "editor",
  "permission": "memory:write",
  "resource": "/memories",
  "action": "POST",
  "granted": true,
  "tenant_id": "tenant_xyz"
}