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 intern ein ag_-Agent-Key erzeugt und ausschließlich gehasht gespeichert — er wird nicht zurückgegeben und nirgends angezeigt. Dieser Key wird heute von keinem API-Auth-Pfad akzeptiert — er ist für künftige agent-scoped Authentifizierung reserviert und wird beim Widerrufen oder Ablehnen des Agents invalidiert. 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: Playground-Traces werden nie on-chain verankert, unabhängig vom konfigurierten Netzwerk des Projekts.
Fehler-Responses
Authentifizierungs- und Autorisierungsfehler liefern einen strukturierten JSON-Body:
{ "error": { "code": "unauthorized", "message": "Ungültiger API-Schlüssel", "request_id": "req-..." } }| 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 einen höheren Tarif (error.code ist forbidden) |
429 | Rate-Limit erreicht — siehe unten |
Verzweigen Sie auf error.code (zum Beispiel unauthorized, forbidden, validation_error), nicht allein auf den HTTP-Status. Die request_id nennen Sie bei Rückfragen; sie steht auch im Antwortkopf x-request-id.
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 (alle Werte unten sind Beispielwerte — die realen Limits Ihres Projekts kommen aus der Live-Tarifkonfiguration):
{
"error": "Rate limit exceeded",
"tier": "pro",
"limit": 20000,
"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.
Bei 429 wiederholt das SDK nicht von selbst. Die Prüf-Funktion verify() liefert die Entscheidung RATE_LIMITED mit retryAfterMs zurück; beachten Sie diesen Wert, bevor Sie erneut senden.