Authentifizierung
Authentifizierung bei der Palveron-API.
Jede Anfrage an die Palveron-API wird mit einem Bearer-Token authentifiziert — immer dem Projekt-API-Schlüssel.
curl -H "Authorization: Bearer pv_live_..." https://gateway.palveron.com/api/v1/verifySchlüsseltypen
| Präfix | Genutzt von | Lebenszyklus |
|---|---|---|
pv_live_ | Server-SDKs, eigenes Backend und die Browser-Guard-Extension | Pro Projekt vergeben, rotierbar unter Einstellungen → API-Schlüssel |
Agent-Keys (ag_)
Bei der Registrierung eines Agents wird zusätzlich ein ag_-Agent-Key erzeugt. Er wird genau einmal in der Registrierungs-Response zurückgegeben, at-rest gehasht gespeichert und beim Widerrufen oder Ablehnen des Agents invalidiert. Dieser Key wird heute von keinem API-Auth-Pfad akzeptiert — er ist für künftige agent-scoped Authentifizierung reserviert. Jeder Aufrufer, auch einer, der für einen einzelnen Agent handelt, authentifiziert sich mit dem Projekt-Key.
Agents werden stattdessen über ihre Agent-ID zugeordnet — eine nackte CUID ohne Präfix (z. B. ckagent...): metadata.agent_id auf Verify-Anfragen, der X-Agent-Id-Header am MCP-Proxy oder der X-Palveron-Agent-Header am Gateway-LLM-Proxy.
Schlüssel nie in die Versionskontrolle committen. Das Dashboard zeigt jeden Schlüssel genau einmal bei der Erstellung. In einem Secrets-Manager (AWS Secrets Manager, GCP Secret Manager, Vault) oder dem Secret-Store der CI/CD-Pipeline ablegen.
Schlüssel-Modus
Jeder Projekt-API-Schlüssel ist ein Live-Schlüssel (Präfix pv_live_); es gibt keinen separaten Test- oder Sandbox-Schlüssel. Das Präfix ändert nicht, wie eine Anfrage abgerechnet oder verankert wird — das ist eine Eigenschaft des Projekts, nicht des Schlüssels.
Für gas-freies Experimentieren den Dashboard-Playground nutzen: Er läuft immer gegen das Coston2-Testnet und verankert nie auf dem Flare-Mainnet, unabhängig vom konfigurierten Netzwerk des Projekts.
Fehler-Responses
Authentifizierungs- und Autorisierungsfehler liefern einen einfachen, menschenlesbaren JSON-Body:
{ "error": "Unauthorized: Invalid API Key" }| Status | Bedeutung |
|---|---|
401 | Fehlender/ungültiger Authorization-Header oder unbekannter/widerrufener Schlüssel |
403 | Schlüssel gültig, aber Aktion nicht erlaubt, oder der Endpoint erfordert ein höheres Tier (Entitlement-Gates liefern z. B. {"error": "feature_not_entitled"}) |
429 | Rate-Limit erreicht — siehe unten |
Es gibt kein maschinenlesbares Fehlercode- oder Request-ID-Feld; auf den HTTP-Status verzweigen und, wo pro Endpoint dokumentiert, auf den error-String.
Rate-Limits
Zwei unabhängige Limits, beide aus der Plan-Konfiguration aufgelöst (null = unbegrenzt, 0 = gesperrt, N = Limit):
- Monatskontingent — Governance-Anfragen pro Monat.
- Requests-per-Minute (RPM) — nur durchgesetzt, wenn der Plan eines setzt.
Ein 429 trägt einen strukturierten Body und Standard-Header:
{
"error": "Rate limit exceeded",
"tier": "pro",
"limit": 50000,
"limit_type": "monthly",
"remaining": 0,
"retry_after_secs": 86400,
"action": "top_up",
"detail": "Rate limit exceeded. Purchase additional governance traces to continue.",
"top_up_available": true
}Header: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-Rate-Limit-Type (rpm / monthly), X-RateLimit-Behavior, X-TopUp-Available.
Die offiziellen SDKs wiederholen transiente 429 mit Exponential Backoff und Jitter; eigene Clients sollten dasselbe tun.