veylant/docs/admin-guide.md

Veylant IA — Admin User Guide

This guide covers day-to-day administration of the Veylant IA platform. All operations require an admin JWT.

1. Overview

The Veylant IA admin dashboard exposes a REST API under /v1/admin/. Key capabilities:

Area	Endpoints
Routing policies	/v1/admin/policies
Audit logs	/v1/admin/logs
Cost reporting	/v1/admin/costs
User management	/v1/admin/users
Feature flags	/v1/admin/flags
Provider status	/v1/admin/providers/status
Rate limits	/v1/admin/rate-limits
GDPR/Compliance	/v1/admin/compliance/*

Interactive documentation: GET /docs

---

2. Routing Policy Management

Routing policies control which AI provider receives each request, based on department, role, model, or sensitivity.

List policies

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/policies

Create a policy

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HR to GPT-4o mini",
    "priority": 10,
    "is_enabled": true,
    "conditions": [
      {"field": "department", "operator": "eq", "value": "HR"}
    ],
    "action": {"provider": "openai", "model": "gpt-4o-mini"}
  }' \
  http://localhost:8090/v1/admin/policies

Seed a template

Pre-built templates for common use cases:

# Available: hr, finance, engineering, catchall
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/policies/seed/hr

Priority order

Rules are evaluated in ascending priority order — lower number = higher priority. The first matching rule wins. Configure a catchall rule with high priority (e.g. 999) as a fallback.

Disable routing engine for a tenant

Set routing_enabled=false to bypass the rules engine and use static prefix routing:

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -d '{"enabled": false}' \
  http://localhost:8090/v1/admin/flags/routing_enabled

---

3. Audit Logs

All requests are logged to ClickHouse. Query via the admin API:

# Last 50 entries
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/logs"

# Filter by provider and time range
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/logs?provider=openai&start=2026-01-01T00:00:00Z&limit=100"

# Filter by minimum sensitivity
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/logs?min_sensitivity=high"

Sensitivity levels: low | medium | high | critical (based on PII entity types detected).

CSV export

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/compliance/export/logs" -o audit-export.csv

---

4. Cost Reporting

# Group by provider
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/costs?group_by=provider"

# Group by department
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/costs?group_by=department&start=2026-01-01T00:00:00Z"

Response includes total_tokens, total_cost_usd, and request_count per group.

Disable billing tracking

If you do not want costs recorded for a tenant (e.g. during a trial period):

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -d '{"enabled": false}' \
  http://localhost:8090/v1/admin/flags/billing_enabled

---

5. User Management

# List users
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/users

# Create a user
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@corp.example",
    "first_name": "Jane",
    "last_name": "Doe",
    "department": "Finance",
    "role": "user"
  }' \
  http://localhost:8090/v1/admin/users

# Update role
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "manager"}' \
  http://localhost:8090/v1/admin/users/{id}

# Soft-delete a user
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/users/{id}

Roles: admin | manager | user | auditor

RBAC rules:

• admin: full access to all models and admin API
• manager: access to all user-allowed models + audit read access
• user: restricted to user_allowed_models from the RBAC config
• auditor: read-only access to logs and costs, cannot use the proxy

---

6. Feature Flags

Feature flags let you toggle module-level behaviour per tenant without a restart.

Built-in flags

Flag	Default	Effect when false
pii_enabled	true	Skips PII anonymization entirely
routing_enabled	true	Uses static prefix routing instead of rules engine
billing_enabled	true	Sets cost_usd = 0 in audit entries
zero_retention	false	PII service does not persist mappings in Redis

# List all flags (tenant + global)
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/flags

# Disable PII for this tenant
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -d '{"enabled": false}' \
  http://localhost:8090/v1/admin/flags/pii_enabled

# Re-enable (or remove tenant override to fall back to global default)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/flags/pii_enabled

---

7. Provider Status

Check the circuit breaker state of each upstream provider:

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/providers/status

States: closed (healthy) | open (failing, requests rejected) | half-open (testing recovery).

---

8. Rate Limit Configuration

# View current config
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/rate-limits/{tenant_id}"

# Update limits (takes effect immediately, no restart needed)
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests_per_min": 2000,
    "burst_size": 400,
    "user_rpm": 200,
    "user_burst": 40,
    "is_enabled": true
  }' \
  "http://localhost:8090/v1/admin/rate-limits/{tenant_id}"

# Remove custom config (reverts to global default)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/rate-limits/{tenant_id}"

---

9. GDPR / EU AI Act Compliance

Processing Registry (Article 30)

# List processing activities
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8090/v1/admin/compliance/entries

# Create a new processing activity
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "use_case_name": "Chatbot RH",
    "legal_basis": "legitimate_interest",
    "purpose": "Automatisation des réponses RH internes",
    "data_categories": ["identifiers", "professional"],
    "recipients": ["HR team"],
    "processors": ["OpenAI Inc."],
    "retention_period": "12 months",
    "security_measures": "AES-256 encryption, access control",
    "controller_name": "Acme Corp DPO"
  }' \
  http://localhost:8090/v1/admin/compliance/entries

EU AI Act Classification

Classify an entry by answering 5 risk questions:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ai_act_answers": {
      "q1": false,
      "q2": false,
      "q3": true,
      "q4": false,
      "q5": true
    }
  }' \
  "http://localhost:8090/v1/admin/compliance/entries/{id}/classify"

Risk levels: minimal (0 yes) | limited (1-2 yes) | high (3-4 yes) | forbidden (5 yes).

GDPR Rights

# Art. 15 — Data subject access request
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/compliance/gdpr/access/user@corp.example"

# Art. 17 — Right to erasure
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8090/v1/admin/compliance/gdpr/erase/user@corp.example?reason=user-request"

The erasure endpoint soft-deletes the user and creates an immutable audit record. It is safe to call even without a database connection (graceful degradation).

---

10. Health & Monitoring

# Service health (no auth required)
curl http://localhost:8090/healthz

# Prometheus metrics (if enabled)
curl http://localhost:8090/metrics

Metrics expose request counts, latency histograms, and error rates per model/provider.