Service-Token Authentifizierung

Service-Tokens sind der primäre Auth-Mechanismus für Kavra-interne Produkte und vertrauenswürdige Integrationen.

Token erhalten

Service-Tokens werden manuell vergeben. Kontaktieren Sie office@kavra.cloud mit folgenden Angaben:

• Name Ihrer Organisation
• Geplanter Use-Case
• Gewünschtes Cockpit-Tier (Starter, Pro, Business)

Kein Self-Service

Während der Beta-Phase gibt es kein Self-Service-Portal für Token-Erstellung. Tokens werden innerhalb von 24h nach Anfrage bereitgestellt.

Header-Format

Alle authentifizierten Requests benötigen den Header:

X-Kavra-Service-Token: sk_your_token_here

Beispiel:

curl -X POST https://siegel.kavra.cloud/api/v1/internal/v1/stamp \
  -H "X-Kavra-Service-Token: sk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"hash": "abcd1234...", "tier": "basic"}'

Welche Endpoints brauchen Auth?

Endpoint-Familie	Auth erforderlich	Header
/api/v1/internal/*	Ja	X-Kavra-Service-Token
/api/v1/agent/*	Ja (x402, geplant)	X-Payment-Transaction
/api/v1/verify/*	Nein	—
/health	Nein	—
/mcp	Ja (für tools/call)	X-Kavra-Service-Token

Fehler-Responses

401 Unauthorized

Token fehlt oder ist ungültig:

{
  "detail": "Ungültiger Service-Token"
}

Häufige Ursachen:

• Header-Name falsch geschrieben (Achtung: X-Kavra-Service-Token, nicht Authorization)
• Token abgelaufen oder widerrufen
• Leerzeichen im Token-Wert

Best Practices

Token-Sicherheit

• Tokens niemals in Client-Side-Code (Browser, Mobile App) einbetten
• Tokens als Umgebungsvariable speichern, nicht im Quellcode
• Bei Kompromittierung sofort office@kavra.cloud kontaktieren

import os
from kavra_siegel import SiegelClient

client = SiegelClient(
    base_url="https://siegel.kavra.cloud",
    service_token=os.environ["KAVRA_SIEGEL_TOKEN"],
)

Rate-Limiting

Alle Endpoints (auch interne) unterliegen Rate-Limiting. Die aktuellen Limits:

Tier	Requests/Minute
Starter	10
Pro	60
Business	200

Bei Überschreitung erhalten Sie 429 Too Many Requests.