← Zpět na hlavní stránku

API Keys - Návod k použití

API KEY AUTHENTICATION - NÁVOD

Status: ✅ IMPLEMENTOVÁNO Datum: 2026-01-25


🔐 CO TO JE

API Key authentication zabezpečuje gateway - každý request musí obsahovat platný API klíč.

Výhody: - ✅ Bezpečný přístup (jen autorizovaní uživatelé) - ✅ Rate limiting (ochrana před zneužitím) - ✅ Usage tracking (statistiky použití) - ✅ Expirable keys (časově omezené klíče)


🚀 JAK TO FUNGUJE

1. VEŘEJNÉ ENDPOINTY (bez API klíče):

# Tyto endpointy jsou veřejné - API klíč NENÍ potřeba
GET  /                    # Gateway info
GET  /health              # Health check
GET  /metrics             # Prometheus metrics
GET  /docs                # Swagger UI
GET  /redoc               # ReDoc dokumentace
GET  /openapi.json        # OpenAPI schema

2. CHRÁNĚNÉ ENDPOINTY (vyžadují API klíč):

# Všechny ostatní endpointy vyžadují API klíč
GET  /api/services        # Seznam služeb
GET  /api/agents          # Seznam agentů
POST /api/banking/loan_assessment
POST /api/aml/company_screening
... (všech 88 agentů)

🔑 JAK ZÍSKAT API KLÍČ

ADMIN (generování klíčů):

# 1. Vygeneruj nový klíč (admin only)
curl -X POST https://api.czechai.io/admin/keys/generate \
  -H "X-Admin-Key: czai_admin_secret_key_change_me" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Client",
    "description": "Klíč pro produkční klienta",
    "owner": "jan.novak@firma.cz",
    "expires_days": 365,
    "rate_limit": 10000,
    "requests_per_minute": 100
  }'

# Response:
{
  "success": true,
  "key_data": {
    "key": "czai_xyzABC123...",  # ⚠️ ULOŽIT! Zobrazí se jen jednou
    "id": 1,
    "prefix": "czai_xyzABC1",
    "name": "Production Client",
    "created_at": "2026-01-25T11:30:00",
    "expires_at": "2027-01-25T11:30:00",
    "rate_limit": 10000,
    "requests_per_minute": 100
  },
  "warning": "Save this key! It will not be shown again."
}

⚠️ DŮLEŽITÉ: API klíč se zobrazí JEN JEDNOU při generování!


📝 JAK POUŽÍVAT API KLÍČ

Varianta 1: X-API-Key header (doporučeno):

curl -X POST https://api.czechai.io/api/banking/loan_assessment \
  -H "X-API-Key: czai_xyzABC123..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000000, "income": 80000}'

Varianta 2: Authorization Bearer:

curl -X POST https://api.czechai.io/api/banking/loan_assessment \
  -H "Authorization: Bearer czai_xyzABC123..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000000, "income": 80000}'

📊 SPRÁVA API KLÍČŮ (Admin)

1. Seznam všech klíčů:

curl https://api.czechai.io/admin/keys/list \
  -H "X-Admin-Key: czai_admin_secret_key_change_me"

# Response:
{
  "count": 3,
  "keys": [
    {
      "id": 1,
      "prefix": "czai_xyzABC1",
      "name": "Production Client",
      "description": "Klíč pro produkční klienta",
      "owner": "jan.novak@firma.cz",
      "created_at": "2026-01-25 11:30:00",
      "expires_at": "2027-01-25 11:30:00",
      "is_active": true
    },
    ...
  ]
}

2. Usage statistiky:

curl "https://api.czechai.io/admin/keys/usage/1?days=7" \
  -H "X-Admin-Key: czai_admin_secret_key_change_me"

# Response:
{
  "key_id": 1,
  "stats": {
    "total_requests": 1542,
    "by_endpoint": [
      {"endpoint": "/api/banking/loan_assessment", "count": 450},
      {"endpoint": "/api/aml/company_screening", "count": 380},
      ...
    ],
    "by_status": {
      "200": 1480,
      "400": 42,
      "500": 20
    },
    "period_days": 7
  }
}

3. Revoke klíč:

curl -X POST https://api.czechai.io/admin/keys/revoke/1 \
  -H "X-Admin-Key: czai_admin_secret_key_change_me"

# Response:
{
  "success": true,
  "message": "Key 1 revoked"
}

⚠️ RATE LIMITING

Každý API klíč má dva limity:

  1. Requests per minute (default: 100/min)
  2. Ochrana proti burst trafficu
  3. Vrací HTTP 429 při překročení

  4. Daily rate limit (default: 10,000/den)

  5. Celkový denní limit
  6. Tracked, ale ne enforced zatím

Příklad rate limit error:

# Po překročení limitu
curl -X POST https://api.czechai.io/api/banking/loan_assessment \
  -H "X-API-Key: czai_xyzABC123..."

# Response: 429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "limit": 100,
  "window": "1 minute"
}

🔒 BEZPEČNOST

Admin Key:

# Default admin key (ZMĚNIT V PRODUKCI!)
ADMIN_API_KEY=czai_admin_secret_key_change_me

# Nastavit environment variable:
export ADMIN_API_KEY="tvůj_silný_admin_klíč"

API Key formát:

czai_<32-char-random-string>

Příklad: czai_xyzABC123def456GHI789jkl012MNO345pqr678STU

Ukládání:


📁 DATABÁZE

Soubor: api_keys.db (SQLite)

Tabulky:

  1. api_keys - Metadata klíčů
  2. key_hash (SHA-256)
  3. key_prefix (prvních 12 znaků pro identifikaci)
  4. name, description, owner
  5. expires_at, is_active
  6. rate_limit, requests_per_minute

  7. api_usage - Usage log

  8. key_id, endpoint, method, status_code
  9. timestamp

  10. rate_limits - Rate limiting tracking

  11. key_id, window_start, request_count

🎯 PŘÍKLADY POUŽITÍ

Python Client:

import requests

API_KEY = "czai_xyzABC123..."
BASE_URL = "https://api.czechai.io"

# Loan assessment
response = requests.post(
    f"{BASE_URL}/api/banking/loan_assessment",
    headers={"X-API-Key": API_KEY},
    json={
        "amount": 5000000,
        "monthly_income": 80000,
        "property_value": 8000000
    }
)

print(response.json())

JavaScript Client:

const API_KEY = "czai_xyzABC123...";
const BASE_URL = "https://api.czechai.io";

// AML screening
fetch(`${BASE_URL}/api/aml/company_screening`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    ico: "12345678",
    name: "ACME s.r.o."
  })
})
.then(res => res.json())
.then(data => console.log(data));

🚨 ERROR RESPONSES

Status Error Meaning
401 API key required Chybí X-API-Key header
403 Invalid or expired API key Neplatný/expirovaný klíč
429 Rate limit exceeded Překročen rate limit

✅ CHECKLIST PRO PRODUKCI


Vytvořeno: 2026-01-25 Autor: CzechAI Team


© 2026 CzechAI | router.czechai.io | API Docs